aboutsummaryrefslogtreecommitdiffstats
path: root/man3
AgeCommit message (Collapse)AuthorFilesLines
2020-04-29setlogmask.3: Note that LOG_UPTO() is included in the next POSIX releaseMichael Kerrisk1-0/+4
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-29cmsg.3: CONFORMING TO: note which CMSG_* APIs are in current and upcoming POSIXMichael Kerrisk1-0/+11
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-29dlopen.3: srcfix: add URL relevant for BUGSMichael Kerrisk1-0/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-28ftw.3: glibc eventually fixed a regression in FTW_SLN behaviorMichael Kerrisk1-33/+21
For details, see: https://bugzilla.redhat.com/show_bug.cgi?id=1422736 http://austingroupbugs.net/view.php?id=1121 https://bugzilla.redhat.com/show_bug.cgi?id=1422736 Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-25ptsname.3: Fix description of failure behaviour of ptsname_r()Bruno Haible1-6/+3
The Linux man page for ptsname_r, when describing the behaviour in the error case, is - not consistent with the future POSIX standard (POSIX Issue 8). - not consistent with musl libc. Find attached a patch to - keep it consistent with what glibc does, - make it consistent with musl libc, - make it consistent with the future POSIX standard (POSIX Issue 8). Details: glibc's implementation of ptsname_r, when it fails, returns the error code as return value AND sets errno. See https://sourceware.org/git/?p=glibc.git;a=blob;f=login/ptsname.c https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/mach/hurd/ptsname.c https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/unix/sysv/linux/ptsname.c musl's implementation of ptsname_r, when it fails, returns the error code but does NOT set errno. See https://git.musl-libc.org/cgit/musl/tree/src/misc/pty.c The proposal to add ptsname_r to POSIX, with text "If successful, the ptsname_r( ) function shall return zero. Otherwise, an error number shall be returned to indicate the error." has been accepted for inclusion in POSIX Issue 8. http://austingroupbugs.net/view.php?id=508 Therefore a portable program should look at the return value from ptsname_r, NOT the errno value. The current text in the man page suggests to look at the errno value, which is wrong (because of musl libc) and not future-proof (because of future POSIX). Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-23newlocale.3: Fix a valgrind issue in example programMichael Kerrisk1-0/+1
See https://bugzilla.kernel.org/show_bug.cgi?id=202977. Reported-by: Piotr Caban <piotr@codeweavers.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-23sem_getvalue.3: Note that glibc's sem_getvalue() doesn't return EINVAL errorsMichael Kerrisk1-0/+3
See https://bugzilla.kernel.org/show_bug.cgi?id=204273 Reported-by: Andrea Galbusera <gizero@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-22getdtablesize.3: Remove redundant statment that getdtablesize() is a library ↵Michael Kerrisk1-2/+2
function Redundant because this is a Section 3 page, and the text also describes the implementation in glibc. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-20posix_spawn.3: tfixJakub Wilk1-2/+2
Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-20psignal.3: wfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-20gethostbyname.3:Michael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-20getopt.3: wfixMichael Kerrisk1-3/+3
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-20exec.3: wfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-20errno.3: ffixMichael Kerrisk1-0/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-20readdir.3: wfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19scanf.3: tfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19sysconf.3: tfixMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19resolver.3: ffixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19strstr.3: srcfix: remove some ancient Linux libc details that were in commentsMichael Kerrisk1-12/+0
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19carg.3: tfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19hypot.3: wfixMichael Kerrisk1-1/+2
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19getmntent.3: ffixMichael Kerrisk1-1/+2
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19sysconf.3: tfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19strftime.3: tfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19erf.3: wfixMichael Kerrisk1-1/+1
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19erf.3: tfixMichael Kerrisk1-2/+2
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-19gcvt.3: wfixMichael Kerrisk1-2/+2
Reported-by: Helge Kreutzmann <debian@helgefjell.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-17posix_spawn.3: ffixMichael Kerrisk1-1/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-17posix_spawn.3: Document the POSIX_SPAWN_SETSID attributeOlivier Gayot1-0/+14
Since glibc 2.26, posix_spawn (2) function accepts the POSIX_SPAWN_SETSID flag. This flag has been accepted by POSIX and should be added to the next major revision. The current support can be enabled with _GNU_SOURCE. Upstream commit in glibc.git: daeb1fa2e1 [BZ 21340] add support for POSIX_SPAWN_SETSID Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org> Signed-off-by: Olivier Gayot <olivier.gayot@sigexec.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-17posix_spawn.3: Clarify by using name of steps rather than syscallsOlivier Gayot1-5/+5
The implementation of the fork() step in posix_spawn(2) relies on either fork(2), vfork(2) or clone(2) depending on the version of the glibc and the arguments passed to posix_spawn(2). It is sometimes ambiguous whether, when we are mentioning "fork(2)", we are referring to the fork() step or the actual fork(2) syscall. This patch hopefully avoids the ambiguity by replacing confusing occurrences by "the xxx() step" where appropriate. Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org> Signed-off-by: Olivier Gayot <olivier.gayot@sigexec.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-17posix_spawn.3: Document POSIX_SPAWN_USEVFORKOlivier Gayot1-0/+12
Added a few lines about POSIX_SPAWN_USEVFORK so that it appears clearly that since glibc 2.24, the flag has no effect. Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org> Signed-off-by: Olivier Gayot <olivier.gayot@sigexec.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-17posix_spawn.3: Document implementation using clone() since glibc 2.24Olivier Gayot1-8/+18
Since glibc 2.24, the use of posix_spawn (2) makes an unconditional call to clone(CLONE_VM | CLONE_VFORK ...) rather than relying on fork (2) or vfork (2). As a consequence, the statements regarding the use of the flag POSIX_SPAWN_USEVFORK and how the function decides whether it should use fork (2) or vfork (2) are obsolete since glibc 2.24. This patch makes a distinction in the manual page between glibc 2.24 and older versions. Upstream commit in glibc.git: 9ff72da471 posix: New Linux posix_spawn{p} implementation Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org> Signed-off-by: Olivier Gayot <olivier.gayot@sigexec.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-16getauxval.3: Minor tweaks to YunQiang Su's patchMichael Kerrisk1-1/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-16getauxval.3: MIPS, AT_BASE_PLATFORM passes ISA levelYunQiang Su1-3/+4
Since Linux 5.7, on MIPS, we use AT_BASE_PLATFORM to pass ISA level. The values may be: mips2, mips3, mips4, mips5, mips32, mips32r2, mips32r6, mips64, mips64r2, mips64r6. This behavior is different with PowerPC. https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=e585b768da111f2c2d413de6214e83bbdfee8f22 Signed-off-by: YunQiang Su <syq@debian.org> ---- v1 -> v2: fix typo Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-14strftime.3: ISO week number can be 52, add exampleUrs Thuermann1-2/+4
A year cannot only begin with week number 53 of the previous year but also with week number 52. Year 2011 is an example for this case, as can be easily seen with GNU date: $ date -d "jan 1 2011" "+%c %V %G" Sat Jan 1 00:00:00 2011 52 2010 Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-12strcmp.3: Add license to example programsMichael Kerrisk1-0/+4
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-12shm_open.3: Add license to example programsMichael Kerrisk1-0/+8
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-11pidfd_getfd.2, select.2, exit.3, time.7, time_namespaces.7: srcfix: Trim ↵Michael Kerrisk1-1/+1
trailing white spaces Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-11getent.1, localedef.1, accept.2, arch_prctl.2, clock_getres.2, ↵Michael Kerrisk24-24/+24
clock_nanosleep.2, connect.2, dup.2, epoll_create.2, epoll_ctl.2, epoll_wait.2, execve.2, getitimer.2, getsockopt.2, gettid.2, inotify_add_watch.2, inotify_init.2, io_submit.2, ioctl.2, lseek.2, madvise.2, mlock.2, mmap.2, mprotect.2, msgctl.2, msgop.2, open_by_handle_at.2, openat2.2, pidfd_open.2, poll.2, prctl.2, quotactl.2, s390_sthyi.2, select.2, select_tut.2, semctl.2, semget.2, semop.2, setns.2, shmctl.2, shmget.2, shmop.2, sigaction.2, stat.2, statx.2, syscalls.2, timer_create.2, timerfd_create.2, unshare.2, wait.2, CPU_SET.3, aio_init.3, atoi.3, des_crypt.3, dirfd.3, fmemopen.3, fopencookie.3, ftok.3, fts.3, getaddrinfo.3, getifaddrs.3, getrpcent.3, gsignal.3, lio_listio.3, nl_langinfo.3, posix_memalign.3, posix_openpt.3, posix_spawn.3, scanf.3, sem_init.3, sem_post.3, shm_open.3, strcmp.3, strftime.3, st.4, elf.5, group.5, proc.5, services.5, aio.7, cgroups.7, feature_test_macros.7, keyrings.7, man-pages.7, namespaces.7, path_resolution.7, sigevent.7, signal.7, socket.7, sysvipc.7, time.7, udp.7: tstamp Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-10strcmp.3: SEE ALSO: add ascii(7)Michael Kerrisk1-0/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-10strcmp.3: Add an example programMichael Kerrisk1-0/+78
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-10strcmp.3: wfixMichael Kerrisk1-2/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-10strcmp.3: Rework text describing return value to be clearerMichael Kerrisk1-5/+36
Reported-by: Andrew Micallef <andrew.micallef@live.com.au> Reported-by: Walter Harms <wharms@bfs.de> Reviewed-by: Andrew Micallef <andrew.micallef@live.com.au> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-10strcmp.3: Note that the comparison is done using unsigned charMichael Kerrisk1-0/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-10accept.2, epoll_create.2, inotify_add_watch.2, open.2, open_by_handle_at.2, ↵Michael Kerrisk3-3/+5
pidfd_open.2, dirfd.3, posix_openpt.3, shm_open.3: Fix clumsy wording around "nonnegative file descriptors" Reported-by: Christian Brauner <christian@brauner.io> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-02pthread_getcpuclockid.3: Minor clarification to usage of 'clockid' argumentMichael Kerrisk1-2/+5
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-04-02clock_getcpuclockid.3, pthread_getcpuclockid.3: wfix: use 'clockid' rather ↵Michael Kerrisk2-3/+3
than 'clock_id' For consistency across pages. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-03-26printf.3: ffixJakub Wilk1-1/+1
Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-03-12sem_post.3: Add a reference to code example code in shm_open(3)Michael Kerrisk1-1/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-03-12sem_init.3: Add references to example code in shm_open(3) and sem_wait(3)Michael Kerrisk1-0/+5
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-03-12shm_open.3: EXAMPLE: add some example programsMichael Kerrisk1-2/+216
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-03-12ftok.3: EXAMPLE: add a reference to the example in semget(2)Michael Kerrisk1-0/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-29getifaddrs.3: EXAMPLE: remove unneeded loop variableMichael Kerrisk1-2/+2
Reported-by: Michael Galassi <michael@galassi.us> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-24strftime.3: tfixEugene Syromyatnikov1-1/+1
Fixes: 13e5f960f353 "strftime.3: Minor tweaks to Eugene Syromyatnikov's patch" Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-24exit.3: Small improvement to the discussion of 'status' argumentMichael Kerrisk1-2/+3
Reported-by: Walter Harms <wharms@bfs.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23strftime.3: Minor tweaks to Eugene Syromyatnikov's patchMichael Kerrisk1-4/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23strftime.3: Expand %E and %O descriptionEugene Syromyatnikov1-3/+26
* man3/strftime.3 (%C): Describe the meaning of %EC conversion specification. (%E): Mention the concept of "era" in description. (%O): Mention that alternative format is related to numeric representation. (%y): Describe the meaning of %Ey conversion specification. (%Y): Describe the meaning of %EY conversion specification. (.SH DESCRIPTION): Mention that the behaviour of %E modifier is governed by ERA locale element and provide ja_JP locale as an example. Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23strftime.3: Tweaks to Eugene Syromyatnikov's patchMichael Kerrisk1-9/+9
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23strftime.3: Refer to the relevant nl_langinfo(3) itemsEugene Syromyatnikov1-0/+65
As it wasn't clear before where this kind of information can be obtained from. * man3/strftime.3 (%a, %A, %b, %B, %c, %p, %r, %x, %X): Add information about the locale elements that can be used to retrieve the relevant information using nl_langinfo() library call. Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23strftime.3: Consistently document fall-back format stringEugene Syromyatnikov1-2/+8
The information is taken from POSIX[1] and the implementations[2][3][4]. [1] https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_05_03 [2] https://sourceware.org/git/?p=glibc.git;a=blob;f=time/strftime_l.c [3] https://git.musl-libc.org/cgit/musl/tree/src/locale/langinfo.c#n15 [4] https://git.uclibc.org/uClibc/tree/libc/misc/locale/locale.c#n992 * man3/strftime.3 (%c, %x, %X): Add information about fall-back format. (%r): Move it behind SU comment. Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23nl_langinfo.3: Tweaks to Eugene Syromyatnikov's patchMichael Kerrisk1-2/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23nl_langinfo.3: Document era-related locale elementsEugene Syromyatnikov1-0/+84
Information is mostly taken from POSIX[1], GNU C Library documentation[2], glibc strftime implementation[3], and Japanese locale definition[4]. [1] https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_05_02 [2] https://www.gnu.org/software/libc/manual/html_node/The-Elegant-and-Fast-Way.html [3] https://sourceware.org/git/?p=glibc.git;a=blob;f=time/strftime_l.c [4] https://sourceware.org/git/?p=glibc.git;a=blob;f=localedata/locales/ja_JP * man3/nl_langinfo.3 (.SH DESCRIPTION): Add information about ERA, ERA_D_T_FMT, ERA_D_FMT, and ERA_T_FMT locale elements. Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23nl_langinfo.3: Add information about AM/PM time format locale elementsEugene Syromyatnikov1-0/+23
* man3/nl_langinfo.3 (.SH DESCRIPTION): Add description for AM_STR, PM_STR, T_FMT_AMPM locale elements. Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23nl_langinfo.3: mention the respective strftime(3) conversion specificationsEugene Syromyatnikov1-3/+25
* man3/nl_langinfo.3 (D_T_FMT, D_FMT, T_FMT, DAY_{1–7}, ABDAY_{1–7}, MON_{1–12}, ABMON_{1–12}): Mention the respective strftime(3) conversion specifications. Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23termios.3: srcfix: Add self to copyrightMichael Kerrisk1-2/+2
I've added quite a few pieces to this page over the years. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23malloc.3: srcfix: Add self to copyrightMichael Kerrisk1-0/+1
By now, I've written quite a bit of the text of this page. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23getopt.3: srcfix: add self to copyrightMichael Kerrisk1-0/+1
I'm the author of various parts of the page, and one of the example programs. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23poll.2, atoi.3, gsignal.3, posix_memalign.3, scanf.3: Remove a few mentions ↵Michael Kerrisk4-18/+20
of the ancient "Linux libc" Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-23getent.1, localedef.1, clock_nanosleep.2, fcntl.2, getitimer.2, ↵Michael Kerrisk11-23/+19
getsockopt.2, inotify_init.2, ioctl.2, mlock.2, mprotect.2, quotactl.2, s390_sthyi.2, semctl.2, shmctl.2, shmget.2, wait.2, CPU_SET.3, aio_init.3, des_crypt.3, fmemopen.3, fopencookie.3, fts.3, getaddrinfo.3, getrpcent.3, lio_listio.3, posix_spawn.3, shm_open.3, st.4, elf.5, group.5, proc.5, services.5, aio.7, feature_test_macros.7, keyrings.7, man-pages.7, sigevent.7, tcp.7, udp.7: Global formatting fix: disfavor nonstandard .TP indents In many cases, these don't improve readability, and (when stacked) they sometimes have the side effect of sometimes forcing text to be justified within a narrow column range. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-09_exit.2, capget.2, fcntl.2, futex.2, listen.2, memfd_create.2, modify_ldt.2, ↵Michael Kerrisk5-5/+5
move_pages.2, open.2, perf_event_open.2, ptrace.2, set_thread_area.2, stime.2, syscall.2, sysctl.2, userfaultfd.2, cmsg.3, exit.3, ftime.3, getpt.3, malloc.3, console_codes.4, loop.4, inotify.7, netlink.7, packet.7, rtnetlink.7, tcp.7, unix.7, vsock.7, ldconfig.8: tstamp Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-08malloc.3: Minor tweaks to Vegard Nossum's patchMichael Kerrisk1-2/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-08malloc.3: realloc() return valueVegard Nossum1-3/+6
One might be tempted to think that realloc() always requests a new allocation before moving the contents over (at least in the case where the new size is bigger than the original). This is not the case; for example, on my system the following program: #include <stdlib.h> #include <stdio.h> #include <unistd.h> int main(int argc, char *argv[]) { void *x = malloc(15); void *y = malloc(32); printf("x = %p\n", x); printf("y = %p\n", y); printf("usable_size(x) = %lu\n", malloc_usable_size(x)); void *z = realloc(x, 24); printf("z = %p\n", z); return 0; } prints: x = 0x1b3a010 y = 0x1b3a030 usable_size(x) = 24 z = 0x1b3a010 Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-08exit.3: Use hex for the status maskBenjamin Peterson1-3/+2
Admittedly, the POSIX specification for exit() also uses octal. However, 0xFF immediately indicates the lowest 8 bits to me whereas I had to think a bit about the octal mask. Cowritten-by: Mike Frysinger <vapier@gentoo.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-07cmsg.3: ffixDmitry V. Levin1-1/+1
Signed-off-by: Dmitry V. Levin <ldv@altlinux.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-05cmsg.3: Modify CMSG_DATA() example to use memcpy()Michael Kerrisk1-3/+1
See previous patch to this page for rationale Reported-by: Rich Felker <dalias@libc.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-05cmsg.3: Clarify alignment issues and correct method of accessing CMSG_DATA()Rich Felker1-0/+6
From an email by Rich Felker: It came to my attention while reviewing possible breakage with move to 64-bit time_t that some applications are dereferencing data in socket control messages (particularly SCM_TIMESTAMP*) in-place as the message type, rather than memcpy'ing it to appropriate storage. This necessarily does not work and is not supportable if the message contains data with greater alignment requirement than the header. In particular, on 32-bit archs, cmsghdr has size 12 and alignment 4, but struct timeval and timespec may have alignment requirement 8. I found at least ptpd, socat, and ssmping doing this via Debian Code Search: https://sources.debian.org/src/ptpd/2.3.1-debian1-4/src/dep/net.c/?hl=1578#L1578 https://sources.debian.org/src/socat/1.7.3.3-2/xio-socket.c/?hl=1839#L1839 https://sources.debian.org/src/ssmping/0.9.1-3/ssmpngcl.c/?hl=307#L307 and I suspect there are a good deal more out there. On most archs they won't break, or will visibly break with SIGBUS, but in theory it's possible that they silently read wrong data and this might happen on some older and more tiny-embedded-oriented archs. I think it's clear to someone who understands alignment and who's thought about it that applications just can't do this, but it doesn't seem to be documented, and an example in cmsg(3) even shows access to int payload via *(int *)CMSG_DATA(cmsg) (of course int is safe because its alignment is <= header alignment, but this is not mentioned). Could we add text, and perhaps change the example, to indicate that in general memcpy needs to be used to copy the payload to/from a suitable object? Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-02-04exec.3: tfixMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-01-21getcwd.3: wfixMike Salvatore1-1/+1
This patch is a minor wording fix in getcwd.3 that changes "In the case getcwd()" to "In the case of getcwd()". This patch should apply cleanly to the master branch of the git repository. Regards, Mike Salvatore From 3b68ad225dbaada2b1b55153dc57807b04531cd6 Mon Sep 17 00:00:00 2001 From: Mike Salvatore <mike.salvatore@canonical.com> Date: Thu, 16 Jan 2020 16:08:08 -0500 Subject: [PATCH] getcwd.3: wfix Signed-off-by: Mike Salvatore <mike.salvatore@canonical.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-01-10malloc.3: Remove duplicate _GNU_SOURCEPetr Vorel1-1/+0
Fixes: d8d701003 ("malloc.3: Since glibc 2.29, realloc() is exposed by defining _DEFAULT_SOURCE") Signed-off-by: Petr Vorel <pvorel@suse.cz> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-01-01getpt.3: Remove mention of O_NOCTTYSamuel Thibault1-1/+1
The glibc implementation of getpt has actually never been setting O_NOCTTY when opening /dev/ptmx or BSD ptys. Signed-off-by: Samuel Thibault <samuel.thibault@ens-lyon.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-12-11nl_langinfo.3: tfixMichael Kerrisk1-1/+1
See https://sourceware.org/bugzilla/show_bug.cgi?id=25255 Reported-by: Weitian LI <liweitianux@live.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-11-23ftime.3: Note that this function is deprecatedMichael Kerrisk1-0/+7
As noted in glibc 2.31 feature notes. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-11-21strtok.3: tfixJashank Jeremy1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-11-13strftime.3: wfixJakub Wilk1-1/+1
Fix comma splice. Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-10-16abort.3: wfixMichael Kerrisk1-1/+1
Reported-by: Mikael Magnusson <mikachu@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-10-12getauxval.3: Clarify that AT_BASE_PLATFORM and AT_EXECFN return pointers to ↵Michael Kerrisk1-2/+2
strings See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=942207 Reported-by: Witold Baryluk <witold.baryluk@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-10-11strptime.3: tfixJakub Wilk1-2/+2
Escape hyphens. Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-10-11localedef.1, close.2, copy_file_range.2, execve.2, get_robust_list.2, ↵Michael Kerrisk12-12/+12
getdomainname.2, gethostname.2, inotify_add_watch.2, io_submit.2, ioctl_fideduperange.2, kcmp.2, kill.2, mmap.2, move_pages.2, perf_event_open.2, ptrace.2, rt_sigqueueinfo.2, sched_setaffinity.2, sched_setparam.2, setns.2, sigaction.2, signalfd.2, statx.2, syscall.2, syscalls.2, uname.2, write.2, errno.3, fexecve.3, getauxval.3, printf.3, pthread_mutex_consistent.3, pthread_mutexattr_init.3, pthread_mutexattr_setrobust.3, pthread_setcancelstate.3, regex.3, strtok.3, strtol.3, ttyname.3, smartpqi.4, core.5, resolv.conf.5, man-pages.7, mq_overview.7, operator.7, pthreads.7, signal-safety.7, sysvipc.7: Update timestamp Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-10-05pthreads.7: Minor tweaks to Carlos O'Donell's patchMichael Kerrisk1-2/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-10-05pthread_setcancelstate.3, pthreads.7: srcfix: wrap source lines at sentence ↵Michael Kerrisk1-1/+2
boundaries Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-10-05pthread_setcancelstate.3, pthreads.7, signal-safety.7: Describe issues with ↵Carlos O'Donell1-1/+4
cancellation points in signal handlers In a recent conversation with Mathieu Desnoyers I was reminded that we haven't written up anything about how deferred cancellation and asynchronous signal handlers interact. Mathieu ran into some of this behaviour and I promised to improve the documentation in this area to point out the potential pitfall. Thoughts? 8< --- 8< --- 8< In pthread_setcancelstate.3, pthreads.7, and signal-safety.7 we describe that if you have an asynchronous signal nesting over a deferred cancellation region that any cancellation point in the signal handler may trigger a cancellation that will behave as-if it was an asynchronous cancellation. This asynchronous cancellation may have unexpected effects on the consistency of the application. Therefore care should be taken with asynchronous signals and deferred cancellation. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-27sched_setparam.2, pthread_mutexattr_init.3, pthread_mutexattr_setrobust.3, ↵Michael Kerrisk4-4/+4
pthread_mutex_consistent.3, strtol.3, sched.7, uts_namespaces.7: SEE ALSO: correct list order Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-27res_nclose.3: Add NEW link to resolver.3Michael Kerrisk1-0/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-27getlogin.3: grfixMichael Kerrisk1-2/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-27copy_file_range.2, fanotify_mark.2, inotify_add_watch.2, ↵Michael Kerrisk1-5/+5
ioctl_fideduperange.2, kcmp.2, prctl.2, get_robust_list.2, tkill.2, ttyname.3: ERRORS: correct alphabetical order Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-26strtok.3: Add portability note for strtok_r() '*saveptr' valueMichael Kerrisk1-1/+9
On some implementations, '*saveptr' must be NULL on first call to strtok_r(). Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-26strtok.3: The caller should not modify 'saveptr' between strtok_r() callsMichael Kerrisk1-1/+2
Reported-by: eponymous alias <eponymousalias@yahoo.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-24getauxval.3: ffixMichael Kerrisk1-3/+6
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-24getauxval.3: srcfix: rewrap source linesMichael Kerrisk1-4/+4
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-24getauxval.3: Add new cache geometry entriesRaphael Moreira Zinsly1-0/+28
Add entries for the new cache geometry values of the auxiliary vector that got included in the kernel. Signed-off-by: Raphael Moreira Zinsly <rzinsly@linux.vnet.ibm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-23strtok.3: Correct description of use of 'saveptr' argument in strtok_r()Michael Kerrisk1-2/+2
Reported-by: eponymous alias <eponymousalias@yahoo.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-13printf.3: Add detail on the first digit with the %e formatVincent Lefevre1-1/+2
This requirement on the first digit with the %e format comes from the ISO C standard. It ensures that all the digits in the output are significant and forbids output with a precision less than requested. Signed-off-by: Vincent Lefevre <vincent@vinc17.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-13fexecve.3: ERRORS: add ENOENTMichael Kerrisk1-0/+8
Reported-by: Simone Piccardi <piccardi@truelite.it> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-13fexecve.3: ENOSYS occurs only if the kernel provides no execveat() syscallMichael Kerrisk1-1/+3
Reported-by: Simone Piccardi <piccardi@truelite.it> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-13regex.3: Minor rewordingMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-13regex.3: ffixMichael Kerrisk1-5/+12
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-13regex.3: srcfix: Wrap source lines at sentence boundariesMichael Kerrisk1-2/+4
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-13regex.3: Document REG_STARTENDRob Landley1-0/+11
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-01errno.3: Minor tweaks to Rasmus Villemoes's patchMichael Kerrisk1-3/+5
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-09-01errno.3: Add some comments on EAGAIN/EWOULDBLOCK and EDEADLK/EDEADLOCKRasmus Villemoes1-2/+3
Signed-off-by: Rasmus Villemoes <rv@rasmusvillemoes.dk> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-08-02pldd.1, bpf.2, chdir.2, clone.2, fanotify_init.2, fanotify_mark.2, intro.2, ↵Michael Kerrisk6-6/+6
ipc.2, mount.2, mprotect.2, msgctl.2, msgget.2, msgop.2, pivot_root.2, pkey_alloc.2, poll.2, prctl.2, semctl.2, semget.2, semop.2, setxattr.2, shmctl.2, shmget.2, shmop.2, tkill.2, dlopen.3, exec.3, ftok.3, getutent.3, on_exit.3, strcat.3, cpuid.4, proc.5, capabilities.7, cgroup_namespaces.7, credentials.7, fanotify.7, mount_namespaces.7, namespaces.7, sched.7, signal.7, socket.7, unix.7, user_namespaces.7, vdso.7, xattr.7, ld.so.8: tstamp Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-20getutent.3: Fix missing include file in EXAMPLEMichael Kerrisk1-0/+1
See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932382 Reported-by: Thorsten Glaser <tg@mirbsd.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-03dlopen.3: wfix: consistently use "object" rather than "library"Michael Kerrisk1-2/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-03dlopen.3: Make it clear that RTLD_NODELETE also affects global variablesMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-03dlopen.3: An object opened with RTLD_LOCAL can be promoted to RTLD_GLOBALMichael Kerrisk1-0/+6
Verified by experiment: $ cat prog.c #include <dlfcn.h> #include <stdio.h> #include <stdlib.h> #include <unistd.h> static int callback(struct dl_phdr_info *info, size_t size, void *data) { printf("\tName = %s\n", info->dlpi_name); return 0; } int main(int argc, char *argv[]) { void *x1Handle, *x2Handle, *yHandle; void (*funcp)(void); char *err; x1Handle = dlopen("./lib_x1.so", RTLD_NOW | RTLD_LOCAL); if (x1Handle == NULL) { fprintf(stderr, "dlopen: %s\n", dlerror()); exit(EXIT_FAILURE); } if (argc > 1) { x2Handle = dlopen("./lib_x2.so", RTLD_NOW | RTLD_GLOBAL); if (x2Handle == NULL) { fprintf(stderr, "dlopen: %s\n", dlerror()); exit(EXIT_FAILURE); } } yHandle = dlopen("./lib_y1.so", RTLD_NOW | RTLD_LOCAL); if (yHandle == NULL) { fprintf(stderr, "dlopen: %s\n", dlerror()); exit(EXIT_FAILURE); } (void) dlerror(); /* Clear dlerror() */ #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wpedantic" funcp = (void (*)(void)) dlsym(yHandle, "y1_enter"); #pragma GCC diagnostic pop err = dlerror(); if (err != NULL) { fprintf(stderr, "dlsym: %s", err); exit(EXIT_FAILURE); } (*funcp)(); exit(EXIT_SUCCESS); } $ cat lib_x1.c #include <stdio.h> void x1_enter(void) { printf("Called %s::%s\n", __FILE__, __func__); } $ cat lib_x2.c #include <stdio.h> void testfunc(void) { printf("Called %s::%s\n", __FILE__, __func__); } $ cat lib_y1.c #include <stdio.h> void testfunc(void) { printf("Called %s::%s\n", __FILE__, __func__); } void y1_enter(void) { extern void y2(void); printf("Called %s\n\n", __func__); testfunc(); } $ cat Build.sh #!/bin/sh CFLAGS="-Wno-implicit-function-declaration -Wl,--no-as-needed" cc $CFLAGS -g -fPIC -shared -o lib_x2.so lib_x2.c cc $CFLAGS -g -fPIC -shared -o lib_x1.so lib_x1.c ./lib_x2.so cc $CFLAGS -g -fPIC -shared -o lib_y1.so lib_y1.c cc $CFLAGS -o prog prog.c -ldl $ sh Build.sh $ ./prog Called y1_enter Called lib_y1.c::testfunc $ ./prog x Called y1_enter Called lib_x2.c::testfunc Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-03dlopen.3: Minor wording fixMichael Kerrisk1-1/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-03dlopen.3: Clarify when an executable's symbols can be used for symbol resolutionMichael Kerrisk1-4/+11
The --export-dynamic linker option is not the only way that main's global symbols may end up in the dynamic symbol table and thus be used to satisfy symbol reference in a shared object. A symbol may also be placed into the dynamic symbol table if ld(1) notices a dependency in another object during the static link. Verified by experiment; see previous commit. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-03dlopen.3: Clarify the rules for symbol resolution in a dlopen'ed objectMichael Kerrisk1-6/+13
The existing text wrongly implied that symbol look up first occurred in the object and then in main, and did not mention whether dependencies of main where used for symbol resolution. Verified by experiment: $ cat prog.c #define _GNU_SOURCE #include <link.h> #include <dlfcn.h> #include <stdio.h> #include <stdlib.h> #include <unistd.h> void /* A function defined in both main and lib_x1 */ prog_x1(void) { printf("Called %s::%s\n", __FILE__, __func__); } /* The following function is forced into prog's dynamic symbol table because of the static link-time reference in lib_m1.so */ void /* A function defined in both main and lib_y1 */ prog_y1_exp(void) { printf("Called %s::%s\n", __FILE__, __func__); } /* The following function is not forced into prog's dynamic symbol table */ void /* A function defined in both main and lib_y1 */ prog_y1_noexp(void) { printf("Called %s::%s\n", __FILE__, __func__); } static int callback(struct dl_phdr_info *info, size_t size, void *data) { printf("\tName = %s\n", info->dlpi_name); return 0; } int main(int argc, char *argv[]) { void *xHandle, *yHandle; void (*funcp)(void); char *err; xHandle = dlopen("./lib_x1.so", RTLD_NOW | RTLD_GLOBAL); if (xHandle == NULL) { fprintf(stderr, "dlopen: %s\n", dlerror()); exit(EXIT_FAILURE); } yHandle = dlopen("./lib_y1.so", RTLD_NOW | RTLD_GLOBAL); if (yHandle == NULL) { fprintf(stderr, "dlopen: %s\n", dlerror()); exit(EXIT_FAILURE); } /* Optionally display the link map() */ if (argc > 1) { printf("Link map as shown from dl_iterate_phdr() callbacks:\n"); dl_iterate_phdr(callback, NULL); printf("\n"); } (void) dlerror(); /* Clear dlerror() */ #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wpedantic" funcp = (void (*)(void)) dlsym(yHandle, "y1_enter"); #pragma GCC diagnostic pop err = dlerror(); if (err != NULL) { fprintf(stderr, "dlsym: %s", err); exit(EXIT_FAILURE); } (*funcp)(); exit(EXIT_SUCCESS); } $ cat lib_m1.c #include <stdio.h> void /* A function defined in both lib_m1 and lib_y1 */ m1_y1(void) { printf("Called %s::%s\n", __FILE__, __func__); } #if 1 void dummy(void) { extern void prog_y1_exp(void); prog_y1_exp(); /* Forces prog_y1_exp into prog's dynamic symbol table, so that it will be visible also to lib_y1.so */ } #endif $ cat lib_x1.c #include <stdio.h> void /* A function defined in both main and lib_x1 */ prog_x1(void) { printf("Called %s::%s\n", __FILE__, __func__); } void /* A function defined in both lib_x1 and lib_y1 */ x1_y1(void) { printf("Called %s::%s\n", __FILE__, __func__); } $ cat lib_y1.c #include <stdio.h> void /* A function defined in both lib_x1 and lib_y1 */ x1_y1(void) { printf("Called %s::%s\n", __FILE__, __func__); } void /* A function defined in both main and lib_y1 */ prog_y1_exp(void) { printf("Called %s::%s\n", __FILE__, __func__); } void /* A function defined in both lib_m1 and lib_y1 */ m1_y1(void) { printf("Called %s::%s\n", __FILE__, __func__); } void /* A function defined in both main and lib_y1 */ prog_y1_noexp(void) { printf("Called %s::%s\n", __FILE__, __func__); } void y1_enter(void) { extern void y2(void); printf("Called %s\n\n", __func__); prog_x1(); prog_y1_exp(); prog_y1_noexp(); x1_y1(); m1_y1(); y2(); } $ cat lib_y2.c #include <stdio.h> void y2(void) { printf("Called %s::%s\n", __FILE__, __func__); } $ cat Build.sh #!/bin/sh CFLAGS="-Wno-implicit-function-declaration -Wl,--no-as-needed" cc $CFLAGS -g -fPIC -shared -o lib_x1.so lib_x1.c cc $CFLAGS -g -fPIC -shared -o lib_y2.so lib_y2.c cc $CFLAGS -g -fPIC -shared -o lib_y1.so lib_y1.c ./lib_y2.so cc $CFLAGS -g -fPIC -shared -o lib_m1.so lib_m1.c #ED="-Wl,--export-dynamic" cc $CFLAGS $ED -Wl,--rpath,$PWD -o prog prog.c -ldl lib_m1.so $ sh Build.sh $ ./prog x Link map as shown from dl_iterate_phdr() callbacks: Name = Name = linux-vdso.so.1 Name = /lib64/libdl.so.2 Name = /home/mtk/tlpi/code/shlibs/dlopen_sym_res_expt/lib_m1.so Name = /lib64/libc.so.6 Name = /lib64/ld-linux-x86-64.so.2 Name = ./lib_x1.so Name = ./lib_y1.so Name = ./lib_y2.so Called y1_enter Called lib_x1.c::prog_x1 Called prog.c::prog_y1_exp Called lib_y1.c::prog_y1_noexp Called lib_x1.c::x1_y1 Called lib_m1.c::m1_y1 Called lib_y2.c::y2 Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-02dlopen.3: Note that symbol use might keep a dlclose'd object in memoryMichael Kerrisk1-1/+8
My earlier commit was in error: commit 4a1af09bd1aae1fdfc783dd017cb5bc392dccc1b Author: Michael Kerrisk <mtk.manpages@gmail.com> Date: Sat Mar 14 21:40:35 2015 +0100 dlopen.3: Amend error in description of dlclose() behavior -If the reference count drops to zero and no other loaded libraries use -symbols in it, then the dynamic library is unloaded. +If the reference count drops to zero, +then the dynamic library is unloaded. I doubted the removed text, because it provide little clue about the scenario. The POSIX dlclose(3) specification actually details the scenario sufficiently: Although a dlclose() 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 func‐ tion 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 dlopen() operation specifying the RTLD_GLOBAL flag might provide a target for dynamic relo‐ cations performed in the processing of other relocatable objects—in such environments, an application may assume that no relocation, once made, shall be undone or remade unless the executable object file containing the relo‐ cated object has itself been removed. Verified by experiment: $ cat openlibs.c # Test program int main(int argc, char *argv[]) { void *libHandle[MAX_LIBS]; int lcnt; if (argc < 2) { fprintf(stderr, "Usage: %s lib-path...\n", argv[0]); exit(EXIT_FAILURE); } lcnt = 0; for (int j = 1; j < argc; j++) { if (argv[j][0] != '-') { if (lcnt >= MAX_LIBS) { fprintf(stderr, "Too many libraries (limit: %d)\n", MAX_LIBS); exit(EXIT_FAILURE); } printf("[%d] Opening %s\n", lcnt, argv[j]); libHandle[lcnt] = dlopen(argv[j], RTLD_NOW | RTLD_GLOBAL); if (libHandle[lcnt] == NULL) { fprintf(stderr, "dlopen: %s\n", dlerror()); exit(EXIT_FAILURE); } lcnt++; } else { /* "-N" closes the Nth handle */ int i = atoi(&argv[j][1]); printf("Closing handle %d\n", i); dlclose(libHandle[i]); } sleep(1); printf("\n"); } printf("Program about to exit\n"); exit(EXIT_SUCCESS); } $ cat lib_x1.c void x1_func(void) { printf("Hello world\n"); } __attribute__((constructor)) void x1_cstor(void) { printf("Called %s\n", __FUNCTION__); } __attribute__((destructor)) void x1_dstor(void) { printf("Called %s\n", __FUNCTION__); } $ cat lib_y1.c void y1_func(void) { printf("Hello world\n"); } __attribute__((constructor)) void y1_cstor(void) { printf("Called %s\n", __FUNCTION__); } __attribute__((destructor)) void y1_dstor(void) { printf("Called %s\n", __FUNCTION__); } static void testref(void) { /* The following reference, to a symbol in lib_x1.so shows that RTLD_GLOBAL may pin a library when it might otherwise have been released with dlclose() */ extern void x1_func(void); x1_func(); } $ cc -shared -fPIC -o lib_x1.so lib_x1.c $ cc -shared -fPIC -o lib_y1.so lib_y1.c $ cc -o openlibs openlibs.c -ldl $ LD_LIBRARY_PATH=. ./openlibs lib_x1.so lib_y1.so -0 -1 [0] Opening lib_x1.so Called x1_cstor [1] Opening lib_y1.so Called y1_cstor Closing handle 0 Closing handle 1 Called y1_dstor Called x1_dstor Program about to exit <end program output> Note that x1_dstor was called only when handle 1 (lib_y1.so) was closed. But, if we edit lib_y1 to remove the reference to x1_func(), things are different: $ cat lib_y1.c # After editing void y1_func(void) { printf("Hello world\n"); } __attribute__((constructor)) void y1_cstor(void) { printf("Called %s\n", __FUNCTION__); } __attribute__((destructor)) void y1_dstor(void) { printf("Called %s\n", __FUNCTION__); } static void testref(void) { // extern void x1_func(void); // x1_func(); } $ cc -shared -fPIC -o lib_y1.so lib_y1.c $ LD_LIBRARY_PATH=. ./openlibs lib_x1.so lib_y1.so -0 -1 [0] Opening lib_x1.so Called x1_cstor [1] Opening lib_y1.so Called y1_cstor Closing handle 0 Called x1_dstor Closing handle 1 Called y1_dstor Program about to exit <end program output> This time, x1_dstor was called when handle 0 (lib_x1.so) was closed. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-02dlopen.3: Clarify that constructors are called only when library is first loadedMichael Kerrisk1-2/+3
And fix a wording error that I introduced back in 2015. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-02dlopen.3: On dlclose(), destructors are called when reference count falls to 0Michael Kerrisk1-1/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-07-02getauxval.3: grfixMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-06-25clone.2, intro.2, ipc.2, msgctl.2, msgget.2, msgop.2, semctl.2, semget.2, ↵Michael Kerrisk1-1/+1
semop.2, shmctl.2, shmget.2, shmop.2, ftok.3, proc.5, namespaces.7: Change reference to svipc(7) to sysvipc(7) Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-06-15on_exit.3: Atack variables may be out of scope when exit handler is invokedMichael Kerrisk1-0/+10
Here's a program for doing experiments: /* on_expt_scope_expt.c (C) Michael Kerrisk, 2019, Licensed GNU GPLv2+ */ char *tos; static void exitFunc(int status, void *p) { int efloc; int *xp = (int *) p; printf("====== Entered exit handler\n"); printf("&efloc = %p (0x%llx)\n", (void *) &efloc, (long long) (tos - (char *) &efloc)); printf("xp = %p (value: %d)\n", (void *) xp, *xp); if (*xp != INIT_VALUE) printf("It looks like the variable passed to the exit handler " "has gone out of scope\n"); /* Produce a core dump, which we can examine with GDB to look at the frames on the stack, if desired */ printf("===\n"); printf("About to abort\n"); abort(); } static void recur(int lev, int *xp) { int rloc; int big[65536-12]; /* 12*4 == 48 other bytes allocated on this stack frame */ tos = (char *) &rloc; big[0] = lev; big[0]++; printf("&rloc = %p (%d) (%d)\n", (void *) &rloc, lev, *xp); if (lev > 1) recur(lev - 1, xp); else { printf("exit() from recur()\n"); exit(EXIT_SUCCESS); } } int main(int argc, char *argv[]) { int lev; int *xp; int xx; if (argc < 2) { fprintf(stderr, "Usage: %s {s|h} [how]\n", argv[0]); fprintf(stderr, "\ts => exitFunc() arg is in main() stack\n"); fprintf(stderr, "\th => exitFunc() arg is allocated on heapn"); fprintf(stderr, "\tIf 'how' is not present, then return from main()\n"); fprintf(stderr, "\tIf 'how' is 0, then exit() from main()\n"); fprintf(stderr, "\tIf 'how' is > 0, then make 'how' recursive " "function calls, and then exit()\n"); exit(EXIT_FAILURE); } tos = (char *) &xp; if (argv[1][0] == 'h') { xp = malloc(sizeof(int)); if (xp == NULL) { perror("malloc"); exit(EXIT_FAILURE); } printf("Argument for exitFunc() is allocated on heap\n"); } else { xp = &xx; printf("Argument for exitFunc() is allocated on stack in main()\n"); } *xp = INIT_VALUE; printf("xp = %p (value: %d)\n", (void *) xp, *xp); printf("===\n"); on_exit(exitFunc, xp); if (argc == 2) { printf("return from main\n"); return 0; } lev = atoi(argv[2]); if (lev < 1) { printf("Calling exit() from main\n"); exit(EXIT_SUCCESS); } else { recur(lev, xp); } } Reported-by: Sami Kerola <kerolasa@iki.fi> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-06-13exec.3: ffixMichael Kerrisk1-0/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-06-13exec.3: Minor tweaks to Matthew Kenigsberg's patchMichael Kerrisk1-2/+14
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-06-13exec.3: Explain function groupingsMatthew Kenigsberg1-25/+14
I've found the exec man page quite difficult to read when trying to find the behavior for a specific function. Since the names of the functions are inline and the order of the descriptions isn't clear, it's hard to find which paragraphs apply to each function. I thought it would be much easier to read if the grouping based on letters is stated.
2019-06-08strcat.3: Fix off-by-one error in example codeMichael Kerrisk1-1/+1
Reported-by: Eric Sanchis <eric.sanchis@iut-rodez.fr> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-16pthread_spin_init.3: tfixMichael Kerrisk1-1/+1
Reported-by: Kumar Chaudhary, Naveen <naveen.kumar.chaudhary@intel.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-09execve.2, setfsgid.2, setfsuid.2, splice.2, fopen.3, malloc_trim.3, ↵Michael Kerrisk6-6/+6
posix_memalign.3, stdarg.3, sysconf.3, tsearch.3, elf.5, hostname.7, inode.7: tstamp Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-06intro.1, execve.2, getcontext.3, passwd.5, bpf-helpers.7: wfixJakub Wilk1-1/+1
Use gender-neutral pronouns. Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05twalk_r.3: New link to twalk(3) pageMichael Kerrisk1-0/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05tsearch.3: Minor tweak to Florian's patchMichael Kerrisk1-1/+1
Use consistent argument names in twalk() and twalk_r(). Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05tsearch.3: Reformat twalk() and twalk_r() prototypes for easier readabilityMichael Kerrisk1-5/+7
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05tsearch.3: SYNOPSIS: clarify that twalk_r() requires _GNU_SOURCEMichael Kerrisk1-3/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05tsearch.3: Minor tweaks to Florian Weimer's patchMichael Kerrisk1-5/+8
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05tsearch.3: Document the twalk_r() function added in glibc 2.30Florian Weimer1-2/+24
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05tsearch.3: Do not use const arguments in twalk() callbackFlorian Weimer1-3/+2
The const specifier is not part of the prototype (it only applies to the implementation), so showing it here confuses the reader. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05sysconf.3: Clearly note that _SC_PAGESIZE and _SC_PAGE_SIZE are synonymsMichael Kerrisk1-1/+9
Reported-by: Hugues Evrard <hevrard@google.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05stdarg.3: Remove the NOTES section describing the ancient varargs macrosMichael Kerrisk1-37/+1
stdarg.h is now 30 years old, and gcc long ago (2004) ceased to implement <varargs.h>. There seems little value in keeping this text. See https://bugzilla.kernel.org/show_bug.cgi?id=202907 Reported-by: Vincent Lefevre <vincent@vinc17.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-05CPU_SET.3: wfixSeth Troisi1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-04posix_memalign.3: Some functions set errnoElliot Hughes1-1/+3
True of bionic, glibc, and musl. (I didn't check elsewhere.) Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-04tsearch.3: SYNOPSIS: add missing definition of 'VISIT' typeMichael Kerrisk1-0/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-05-04mallinfo.3: Further discourage use of mallinfo()Elliott Hughes1-1/+8
The BUGS section already explains why you need to be cautious about using mallinfo, but given the number of bug reports we see on Android, it seems not many people are reading that far. Call it out up front. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-04-14getpt.3: tfixJakub Wilk1-1/+1
Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-04-14malloc_trim.3: Minor fixes to Carlos's patchMichael Kerrisk1-2/+4
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-04-14malloc_trim.3: Update trimming informationCarlos O'Donell1-8/+16
Since glibc 2.8, commit 68631c8eb92, the malloc_trim function has iterated over all arenas and free'd back to the OS all page runs that were free. This allows an application to call malloc_trim to consolidate fragmented chunks and free back any pages it can to potentially reduce RSS usage. This correctness of the man page was recently brought to light by an article [1] where Ruby developers discovered that malloc_trim did not behave as the man page indicated. This change makes it clear that the intent of malloc_trim is to trim all space that is no longer needed, and any restrictions are implementation details. In the notes we highlight the change in behaviour for post glibc 2.8 and pre glibc 2.8. [1] https://www.joyfulbikeshedding.com/blog/2019-03-14-what-causes-ruby-memory-bloat.html#a-magic-trick-trimming Signed-off-by: Carlos O'Donell <carlos@redhat.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-04-14fopen.3: Minor tweaks to Elliot's patchMichael Kerrisk1-1/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-04-14fopen.3: Explain BSD vs glibc "a+" differenceenh1-2/+4
Where is the initial read position for an "a+" stream? POSIX leaves this unspecified. Most BSD man pages are silent, and MacOS has the ambiguous "The stream is positioned at the end of the file", not differentiating between reads and writes other than to say that fseek(3) does not affect writes. glibc's documentation explicitly specifies that the initial read position is the beginning of the file. My new wording is based on the BSD implementations, so you may prefer to replace the non-glibc section with "unspecified", or indeed remove all claims about the initial read position. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-04-14stdarg.3: Add a note that ... in function signature means a variadic functionMichael Kerrisk1-1/+2
Egmont suggested adding this, because the string "..." appears at several other points in the page, but just to indicate that some text is omitted from example code. Reported-by: Egmont Koblinger <egmont@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-03-08execve.2, exec.3: Consistently use the term 'pathname' (not 'path')Michael Kerrisk1-3/+3
Reported-by: Dr. Jürgen Sauermann <mail@xn--jrgen-sauermann-zvb.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-03-08exec.3: Minor wording fix in subsection titleMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-03-08strerror.3: Don't discuss buffer size for strerror_l()Jakub Wilk1-3/+1
Unlike strerror_r(), strerror_l() doesn't take buffer length as an argument. Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-03-08resolver.3: Mention that some functions set 'h_errno'Michael Kerrisk1-0/+14
Reported-by: Wladimir Mutel <muwlgr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-03-08strtol.3, strtoul.3: SEE ALSO: add strtoimax(3), strtoumax(3)Jakub Wilk2-2/+4
Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-03-06getent.1, iconv.1, ldd.1, locale.1, localedef.1, memusage.1, memusagestat.1, ↵Michael Kerrisk158-158/+158
pldd.1, sprof.1, time.1, _syscall.2, accept.2, add_key.2, adjtimex.2, bind.2, bpf.2, capget.2, chown.2, chroot.2, clock_getres.2, clone.2, connect.2, copy_file_range.2, epoll_ctl.2, epoll_wait.2, eventfd.2, fanotify_init.2, fanotify_mark.2, fcntl.2, fsync.2, futex.2, getcpu.2, getdents.2, getgid.2, getgroups.2, getpid.2, gettid.2, gettimeofday.2, getuid.2, getxattr.2, inotify_add_watch.2, inotify_init.2, ioctl_fat.2, ioctl_ns.2, ioctl_userfaultfd.2, ioprio_set.2, kcmp.2, kexec_load.2, keyctl.2, listxattr.2, lseek.2, madvise.2, memfd_create.2, migrate_pages.2, mount.2, mprotect.2, mremap.2, msgctl.2, msgop.2, nfsservctl.2, open_by_handle_at.2, perf_event_open.2, pipe.2, pivot_root.2, pkey_alloc.2, poll.2, posix_fadvise.2, prctl.2, readahead.2, readdir.2, readlink.2, reboot.2, recvmmsg.2, removexattr.2, rename.2, request_key.2, s390_guarded_storage.2, s390_runtime_instr.2, s390_sthyi.2, sched_setaffinity.2, sched_setattr.2, sched_setparam.2, seccomp.2, select.2, select_tut.2, semctl.2, sendmmsg.2, set_thread_area.2, setgid.2, setns.2, setuid.2, setxattr.2, shmctl.2, sigaction.2, signalfd.2, sigsuspend.2, socket.2, socketpair.2, spu_run.2, stat.2, statx.2, subpage_prot.2, syscalls.2, sysctl.2, tee.2, timer_create.2, timerfd_create.2, truncate.2, uname.2, unshare.2, userfaultfd.2, ustat.2, vmsplice.2, write.2, CPU_SET.3, __ppc_get_timebase.3, alloca.3, argz_add.3, asprintf.3, backtrace.3, basename.3, bsd_signal.3, bstring.3, bswap.3, bzero.3, cacos.3, cacosh.3, catan.3, catanh.3, catgets.3, clock_getcpuclockid.3, cmsg.3, confstr.3, ctermid.3, ctime.3, des_crypt.3, dl_iterate_phdr.3, dlinfo.3, dlsym.3, duplocale.3, end.3, endian.3, errno.3, exec.3, exit.3, ferror.3, fgetws.3, fmemopen.3, fnmatch.3, fopencookie.3, fputws.3, frexp.3, ftw.3, get_nprocs_conf.3, get_phys_pages.3, getaddrinfo.3, getaddrinfo_a.3, getdate.3, getgrouplist.3, getifaddrs.3, getline.3, getlogin.3, getmntent.3, getnameinfo.3, getopt.3, getpass.3, getprotoent_r.3, getpwnam.3, getservent_r.3, getsubopt.3, glob.3, gnu_get_libc_version.3, hsearch.3, if_nameindex.3, index.3, inet.3, inet_net_pton.3, inet_pton.3, insque.3, isatty.3, iswblank.3, iswspace.3, lockf.3, makecontext.3, mallinfo.3, malloc.3, malloc_hook.3, malloc_info.3, mallopt.3, matherr.3, mbrtowc.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, mcheck.3, memchr.3, mq_getattr.3, mq_notify.3, newlocale.3, nl_langinfo.3, offsetof.3, perror.3, posix_spawn.3, printf.3, pthread_attr_init.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_getattr_default_np.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_mutexattr_setrobust.3, pthread_rwlockattr_setkind_np.3, pthread_setaffinity_np.3, pthread_setname_np.3, pthread_setschedparam.3, pthread_sigmask.3, putenv.3, qsort.3, rand.3, random.3, readdir.3, regex.3, resolver.3, rpmatch.3, rtime.3, scanf.3, sem_wait.3, setaliasent.3, setbuf.3, stpcpy.3, stpncpy.3, strcat.3, strchr.3, strcmp.3, strcpy.3, strdup.3, strerror.3, strfromd.3, strfry.3, strftime.3, string.3, strlen.3, strnlen.3, strsep.3, strstr.3, strtok.3, strtol.3, strtoul.3, strverscmp.3, strxfrm.3, system.3, termios.3, trunc.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscat.3, wcscpy.3, wcslen.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcsrtombs.3, wcsstr.3, wcstok.3, wcstombs.3, wcwidth.3, wprintf.3, xcrypt.3, console_codes.4, dsp56k.4, full.4, initrd.4, lirc.4, loop.4, st.4, tty.4, vcs.4, charmap.5, core.5, host.conf.5, locale.5, proc.5, repertoiremap.5, resolv.conf.5, termcap.5, tmpfs.5, tzfile.5, aio.7, capabilities.7, cgroup_namespaces.7, cgroups.7, charsets.7, complex.7, epoll.7, fanotify.7, feature_test_macros.7, inotify.7, ip.7, locale.7, man-pages.7, man.7, namespaces.7, pid_namespaces.7, pkeys.7, pthreads.7, rtld-audit.7, sched.7, signal.7, sock_diag.7, socket.7, tcp.7, udp.7, unicode.7, user_namespaces.7, utf-8.7, zdump.8, zic.8: tstamp Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-03-06dlsym.3: Describe a case where a symbol value may be NULLMichael Kerrisk1-3/+15
Remove a longstanding mystery in the text of the page, by explaining a case where the value returned for a symbol may be NULL. (However, there are presumably other cases, since the text in the dlsym(3) manual page pre-dates the invention of IFUNCs.) See also https://stackoverflow.com/questions/13941944/why-can-the-value-of-the-symbol-returned-by-dlsym-be-null Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27locale.1, memusage.1, pldd.1, _syscall.2, add_key.2, bind.2, bpf.2, chown.2, ↵Michael Kerrisk134-471/+471
clone.2, copy_file_range.2, eventfd.2, execve.2, futex.2, getdents.2, getrlimit.2, ioctl_fat.2, ioctl_ns.2, kcmp.2, kexec_load.2, keyctl.2, listxattr.2, lseek.2, membarrier.2, memfd_create.2, mmap.2, mprotect.2, msgop.2, open_by_handle_at.2, perf_event_open.2, pipe.2, readdir.2, readlink.2, readv.2, recvmmsg.2, request_key.2, sched_setaffinity.2, seccomp.2, select.2, select_tut.2, sendmmsg.2, setns.2, signalfd.2, spu_run.2, stat.2, sysctl.2, tee.2, timer_create.2, timerfd_create.2, truncate.2, uname.2, unshare.2, userfaultfd.2, ustat.2, wait.2, CPU_SET.3, __ppc_get_timebase.3, argz_add.3, asprintf.3, backtrace.3, basename.3, bswap.3, bzero.3, cacos.3, cacosh.3, catan.3, catanh.3, catgets.3, clock_getcpuclockid.3, confstr.3, ctime.3, dl_iterate_phdr.3, dlinfo.3, duplocale.3, encrypt.3, end.3, endian.3, fgetws.3, fmemopen.3, fopencookie.3, fputws.3, frexp.3, ftw.3, get_nprocs_conf.3, get_phys_pages.3, getaddrinfo.3, getaddrinfo_a.3, getdate.3, getgrouplist.3, getifaddrs.3, getline.3, getlogin.3, getopt.3, getpass.3, getprotoent_r.3, getpwnam.3, getservent_r.3, getsubopt.3, glob.3, gnu_get_libc_version.3, hsearch.3, if_nameindex.3, index.3, inet.3, inet_net_pton.3, inet_pton.3, insque.3, iswblank.3, iswspace.3, makecontext.3, mallinfo.3, malloc_hook.3, malloc_info.3, mallopt.3, matherr.3, mbrtowc.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, mcheck.3, memchr.3, mq_getattr.3, mq_notify.3, newlocale.3, nl_langinfo.3, offsetof.3, perror.3, posix_spawn.3, printf.3, pthread_attr_init.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_create.3, pthread_getattr_default_np.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_mutexattr_setrobust.3, pthread_setaffinity_np.3, pthread_setname_np.3, pthread_setschedparam.3, pthread_sigmask.3, qsort.3, rand.3, readdir.3, regex.3, rpmatch.3, rtime.3, scanf.3, sem_wait.3, setaliasent.3, setbuf.3, stpcpy.3, stpncpy.3, strcat.3, strchr.3, strcpy.3, strdup.3, strerror.3, strfromd.3, strftime.3, strlen.3, strnlen.3, strsep.3, strstr.3, strtok.3, strtol.3, strtoul.3, strverscmp.3, strxfrm.3, termios.3, tsearch.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscat.3, wcscpy.3, wcslen.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcsrtombs.3, wcsstr.3, wcstok.3, wcstombs.3, wcwidth.3, wprintf.3, console_codes.4, dsp56k.4, full.4, initrd.4, loop.4, vcs.4, charmap.5, core.5, elf.5, locale.5, proc.5, repertoiremap.5, sysfs.5, termcap.5, aio.7, bpf-helpers.7, cgroups.7, charsets.7, complex.7, fanotify.7, feature_test_macros.7, inotify.7, locale.7, man-pages.7, man.7, pkeys.7, pthreads.7, rtld-audit.7, sock_diag.7, unix.7, user_namespaces.7, utf-8.7: Use '\e' rather than '\\' to get a backslash Quoting Branden: *roff escape sequences may sometimes look like C escapes, but that is misleading. *roff is in part a macro language and that means recursive expansion to arbitrary depths. You can get away with "\\" in a context where no macro expansion is taking place, but try to spell a literal backslash this way in the argument to a macro and you will likely be unhappy with results. Try viewing the attached file with "man -l". "\e" is the preferred and portable way to get a portable "escape literal" going back to CSTR #54, the original Bell Labs troff paper. groff(7) discusses the issue: \\ reduces to a single backslash; useful to delay its interpretation as escape character in copy mode. For a printable backslash, use \e, or even better \[rs], to be independent from the current escape character. As of groff 1.22.4, groff_man(7) does as well: \e Widely used in man pages to represent a backslash output glyph. It works reliably as long as the .ec request is not used, which should never happen in man pages, and it is slightly more portable than the more exact ‘\(rs’ (“reverse solidus”) escape sequence. People not concerned with portability to extremely old troffs should probably just use \(rs (or \[rs]), as it means "the backslash glyph", not "the glyph corresponding to whatever the current escape character is". Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27adjtimex.2, futex.2, mremap.2, seccomp.2, getnameinfo.3, random.3, ↵Michael Kerrisk2-4/+4
console_codes.4, sysfs.5, sched.7, unicode.7: Use zero‐width space in appropriate locations Quoting Branden: *roff systems will interpret the period in the unpatched page as sentence-ending punctuation and put inter-sentence spacing after it. (This might not be visible on nroff/terminal devices, but it is more likely to be on typesetter/PostScript/PDF output). groff_man(7) in groff 1.22.4 attempts to throw man page writers a bone here: \& Zero‐width space. Append to an input line to prevent an end‐of‐ sentence punctuation sequence from being recognized as such, or insert at the beginning of an input line to prevent a dot or apostrophe from being interpreted as the beginning of a roff request. Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27fseeko.3: srcfixBjarni Ingi Gislason1-1/+0
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27malloc.3: srcfixMichael Kerrisk1-1/+0
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27pthread_mutex_consistent.3: ffixMichael Kerrisk1-1/+1
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27scanf.3: ffixMichael Kerrisk1-4/+4
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27signbit.3: ffixMichael Kerrisk1-1/+1
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27man3/t-v.3: srcfix: Use a single-font-style macro for a single argumentBjarni Ingi Gislason13-30/+30
Use a single-font-style macro (".B", ".I") for a single argument. Remove unneeded quotation marks ("). The output from "nroff" and "groff" is unchanged, except for the change 1) '-1' to '\-1' in the file "timegm.3" 2) to separate ',' from a word in the file "uselocale.3". Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27wcsncmp.3: ffixMichael Kerrisk1-1/+1
Reported-by: wcsncmp.3 Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27fallocate.2, futex.2, getrandom.2, mprotect.2, posix_spawn.3, ↵Michael Kerrisk1-1/+1
address_families.7, ipv6.7, sock_diag.7, socket.7: ffix Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27fallocate.2, getgid.2, getpid.2, getuid.2, lseek.2, set_thread_area.2, ↵Michael Kerrisk1-2/+4
tzset.3: srcfix: fix some unconventional markup No (intended) changes to generated output Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-27keyctl.2, mlock.2, timerfd_create.2, write.2, nl_langinfo.3, posix_spawn.3: ffixMichael Kerrisk2-3/+3
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-26exec.3: execv(3) does not use execv(2) on sparc/sparc64Michael Kerrisk1-1/+6
Reported-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-26des_crypt.3, encrypt.3: The functions described in these pages are removed ↵Michael Kerrisk2-0/+22
in glibc 2.28 These functions were removed because they use DES, which is no longer considered secure. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-26isatty.3: srcfixMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-25isatty.3: Most non-tty files nowadays result in the error ENOTTYMichael Kerrisk1-5/+7
Historically, at least FIFOs and pipes yielded the error EINVAL. Reported-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-02-25exec.3: Note that SPARCC provides an execv() system callMichael Kerrisk1-0/+7
Reported-by: Eugene Syromyatnikov <evgsyr@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-01-10bstring.3: Correct argument list for memmem() prototypeMichael Kerrisk1-2/+2
Reported-by: Emil Fihlman <emil.fihlman@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-01-10bsd_signal.3: Fix the wrong version of _POSIX_C_SOURCEXiao Yang1-1/+1
According to the latest glibc, the bsd_signal() function is just declared when POSIX.1-2008 (or newer) instead of POSIX.1-2001 is not set since glibc v2.26. Please see the following code from signal/signal.h: ----------------------------------------------------------------- /* The X/Open definition of `signal' conflicts with the BSD version. So they defined another function `bsd_signal'. */ extern __sighandler_t bsd_signal (int __sig, __sighandler_t __handler) __THROW; ----------------------------------------------------------------- Signed-off-by: Xiao Yang <yangx.jy@cn.fujitsu.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2019-01-10errno.3: Mention that errno(1) is part of the 'moreutils' packageMichael Kerrisk1-1/+3
Reported-by: Robert P. J. Day <rpjday@crashcourse.ca> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-27ioctl_console.2, ctime.3: tfixMichael Kerrisk1-1/+1
Reported-by: Anatoly Borodin <anatoly.borodin@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-24system.3: Note that system() can fail for the same reasons as fork(2)Michael Kerrisk1-0/+4
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-24system.3: ffixMichael Kerrisk1-1/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-24system.3: Mention that 'errno' is set on errorArkadiusz Drabczyk1-1/+1
Corresponding system.3p already mentions that. Tested with glibc and musl. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-17getaddrinfo.3: Fix off-by-one error in example client programMichael Kerrisk1-1/+1
Reported-by: Eric Sanchis <eric.sanchis@iut-rodez.fr> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-17pthread_rwlockattr_setkind_np.3: tfixMichael Kerrisk1-1/+1
Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-17pthread_rwlockattr_setkind_np.3: Remove bug notesCarlos O'Donell1-13/+25
The notes in pthread_rwlockattr_setkind_np.3 imply there is a bug in glibc's implementation of PTHREAD_RWLOCK_PREFER_WRITER_NP (a non-portable constant anyway), but this is not true. The implementation of PTHREAD_RWLOCK_PREFER_WRITER_NP is made almost impossible by the POSIX standard requirement that reader locks be allowed to be recursive, and that requirement makes writer preference deadlock without an impossibly complex requirement that we track all reader locks. Therefore the only sensible solution was to add PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP and disallow recursive reader locks if you want writer preference. This patch removes the bug description and documents the current state and recommendations for glibc. I have also updated bug 7057 with this information, answering Steven Munroe's almost 10 year old question :-) I hope Steven is enjoying his much earned retirement. Should we move the glibc discussion to some footnote? Some libc may be able to implement the requirement to avoid deadlocks in the future, but I doubt it (fundamental CS stuff). Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-17ioctl_userfaultfd.2, madvise.2, memfd_create.2, migrate_pages.2, mmap.2, ↵Mike Rapoport1-1/+1
shmget.2, subpage_prot.2, userfaultfd.2, malloc.3, proc.5, sysfs.5, tmpfs.5: Update paths for in-kernel memory management documentation files Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-10system.3: Use '(char *) NULL' rather than '(char *) 0'Michael Kerrisk1-1/+1
Reported-by: Jonny Grant <jg@jguk.org> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-09system.3: ffixMichael Kerrisk1-1/+5
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-09system.3: wfixMichael Kerrisk1-3/+3
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-09resolver.3: Add documentation of res_nclose()Michael Becker1-1/+12
I found the neccessary information in the glibc sources. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-09strfry.3: Remove incorrect reference to rand(3)Keith Thompson1-4/+1
The strfry(3) function does not use rand(). The original version from 1995 did, but it was changed to use a different PRNG in glibc commit 4770745624b7f7f25623f1f10d46a4c4d6aec25c, 1996-12-04. This C program demonstrates the behavior. By not calling srand(), it gets the same values for successive calls to rand(), but strfry() returns a different value each time the program is run. If strfry() called srand(), it would alter the sequence of numbers return by rand(). int main(void) { printf("%d\n", rand()); char alphabet[] = "abcdefghijklmnopqrstuvwxyz"; puts(strfry(alphabet)); printf("%d\n", rand()); } Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-05getmntent.3: Clarify that endmntent() should be used rather than fclose()Elliot Hughes1-0/+4
This doesn't actually matter on any C library I know of --- they all just do a NULL check and forward to fclose(3). (The actual mistake I saw was someone not realizing that they had to call *anything*.) Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-05ferror.3: Warn about closing the result of fileno()Elliot Hughes1-1/+9
Since adding checking to Android's bionic for file descriptor double-closes, we've found that the most common cause of these bugs is incorrect use of fileno(3). There appears to be a common misconception that it transfers ownership of the file descriptor to the caller. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-11-02lockf.3: ERRORS: add EINTRIan Turner1-0/+5
Ian Turner: The exact return calls are at the discretion of the underlying VFS, but I'm pretty sure that EINTR is a possibility. Or, if it's not, then the flock() manpage should be amended accordingly, since the two share the same underlying implementation. mtk: lockf(3) is implemented on top of fcntl() locking, so EINTR is of course a possibility. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-10-27remainder.3: tfixJakub Wilk1-1/+0
Remove stray words. Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-10-21pthread_rwlockattr_setkind_np.3: spfixJakub Wilk1-1/+1
Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-10-21pthread_setname_np.3: Explain _np suffixJakub Wilk1-1/+2
Add text to CONFORMING TO explaining that the "_np" suffix is because these functions are non-portable. Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-10-14alloca.3: Prevent any misunderstanding about when allocated memory is releasedMichael Kerrisk1-0/+7
Perhaps some people might misunderstand memory allocated by alloca() to be like other memory allocated on the stack: that when the allocation (or the pointer to the allocation) goes out of scope, the memory is freed. Add some text to prevent that misunderstanding. Reported-by: Robin Kuzmin <kuzmin.robin@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-10-14atoi.3: tfixMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-10-14getlogin.3: tfixMichael Kerrisk1-1/+1
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2018-10-14ttyslot.3: tfixMichael Kerrisk1-2/+2
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>