1 ==================== Changes in man-pages-4.14 ====================
3 Released: ????-??-??, Paris
9 The following people contributed patches/fixes or (noted in brackets
10 in the changelog below) reports, notes, and ideas that have been
11 incorporated in changes in this release:
13 Adhemerval Zanella <adhemerval.zanella@linaro.org>
14 Adrian Bunk <bunk@kernel.org>
15 Ahmad Fatoum <ahmad@a3f.at>
16 Andrea Arcangeli <aarcange@redhat.com>
17 Bastien Roucaries <roucaries.bastien@gmail.com>
18 Breno Leitao <leitao@debian.org>
19 Carlos O'Donell <carlos@redhat.com>
20 Christian Brauner <christian.brauner@ubuntu.com>
21 Christoph Hellwig <hch@lst.de>
22 Colm MacCárthaigh <colm@allcosts.net>
23 Craig Ringer <craig.ringer@2ndquadrant.com>
24 Cristian Rodríguez <crrodriguez@opensuse.org>
25 David Eckardt <david.eckardt@sociomantic.com>
26 Don Brace <don.brace@microsemi.com>
27 Elliot Hughes <enh@google.com>
28 Eric W. Biederman <ebiederm@xmission.com>
29 Fabio Scotoni <fabio@esse.ch>
30 Fangrui Song <i@maskray.me>
31 Florian Weimer <fweimer@redhat.com>
32 G. Branden Robinson <g.branden.robinson@gmail.com>
33 Goldwyn Rodrigues <rgoldwyn@suse.com>
34 Grégory Vander Schueren <gregory.vanderschueren@tessares.net>
35 Jakub Wilk <jwilk@jwilk.net>
36 Jann Horn <jannh@google.com>
37 Jeff Layton <jlayton@redhat.com>
38 Jens Axboe <axboe@kernel.dk>
39 Jonny Grant <jg@jguk.org>
40 Julien Gomes <julien@arista.com>
41 Kees Cook <keescook@chromium.org>
42 Křištof Želechovski <giecrilj@stegny.2a.pl>
43 Lennart Poettering <lennart@poettering.net>
44 Lucas Werkmeister <mail@lucaswerkmeister.de>
45 Marcus Folkesson <marcus.folkesson@gmail.com>
46 Marin H. <mar-tSIEzQ@neutronstar.noip.me>
47 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
48 Matthew Wilcox <willy@infradead.org>
49 Michael Kerrisk <mtk.manpages@gmail.com>
50 Michal Hocko <mhocko@kernel.org>
51 Michał Zegan <webczat_200@poczta.onet.pl>
52 Mihir Mehta <mihir@cs.utexas.edu>
53 Mike Frysinger <vapier@chromium.org>
54 Mike Kravetz <mike.kravetz@oracle.com>
55 Mike Rapoport <rppt@linux.vnet.ibm.com>
56 Miklos Szeredi <mszeredi@redhat.com>
57 NeilBrown <neilb@suse.com>
58 Oliver Ebert <oe@outputenable.net>
59 Pedro Alves <palves@redhat.com>
60 Per Böhlin <Per.Bohlin@zenterio.com>
61 Peter Zijlstra <peterz@infradead.org>
62 Petr Malat <oss@malat.biz>
63 Petr Uzel <petr.uzel@suse.cz>
64 Prakash Sangappa <prakash.sangappa@oracle.com>
65 Raghavendra D Prabhu <me@rdprabhu.com>
66 Rahul Bedarkar <rpal143@gmail.com>
67 Ram Pai <linuxram@us.ibm.com>
68 Richard Knutsson <richard.knutsson@abelko.se>
69 Rik van Riel <riel@redhat.com>
70 Scott Vokes <vokes.s@gmail.com>
71 Seonghun Lim <wariua@gmail.com>
72 Stas Sergeev <stsp@list.ru>
73 Stefan Puiu <stefan.puiu@gmail.com>
74 Thomas Gleixner <tglx@linutronix.de>
75 Tobias Klausmann <klausman@schwarzvogel.de>
76 Tomas Pospisek <tpo@sourcepole.ch>
77 Tyler Hicks <tyhicks@canonical.com>
78 Victor Porton <porton@narod.ru>
79 Walter Harms <wharms@bfs.de>
80 Wesley Aptekar-Cassels <w.aptekar@gmail.com>
81 Yubin Ruan <ablacktshirt@gmail.com>
82 Zack Weinberg <zackw@panix.com>
83 Дилян Палаузов <dilyan.palauzov@aegee.org>
85 Apologies if I missed anyone!
88 New and rewritten pages
89 -----------------------
92 Michael Kerrisk [Peter Zijlstra, Thomas Gleixner, Zack Weinberg,
94 New page describing pthread_spin_init(3) and pthread_spin_destroy(3)
97 Michael Kerrisk [Carlos O'Donell]
98 New page describing functions that lock and unlock spin locks
99 Add a page describing pthread_spin_lock(3), pthread_spin_unlock(3),
100 and pthread_spin_trylock(3).
103 Don Brace [Michael Kerrisk, G. Branden Robinson]
104 Document the smartpqi SCSI driver
107 Tomáš Pospíšek, Eric Biederman, Michael Kerrisk
108 New page document veth virtual ethernet devices
109 Based on a page from Tomáš Pospíšek, with some clean-ups by mtk.
117 This function was in libc4 and libc5, but never part
118 of glibc. It ceased to be relevant nearly 20 years
119 ago. Time to remove the man page.
122 Newly documented interfaces in existing pages
123 ---------------------------------------------
127 Prakash Sangappa [Andrea Arcangeli, Mike Rapoport]
128 Add description for UFFD_FEATURE_SIGBUS
131 Rik van Riel [Colm MacCárthaigh, Michael Kerrisk]
132 Document MADV_WIPEONFORK and MADV_KEEPONFORK
134 Note fork() and execve() semantics for wipe-on-fork setting
138 Update membarrier manpage for 4.14
139 Add documentation for these new membarrier() commands:
140 MEMBARRIER_CMD_PRIVATE_EXPEDITED
141 MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED
145 Add description of MFD_HUGETLB (hugetlbfs) support
146 hugetlbfs support for memfd_create() was recently merged by Linus
147 and should be in the Linux 4.14 release. To request hugetlbfs
148 support a new memfd_create() flag (MFD_HUGETLB) was added.
152 Document RWF_NOWAIT added in Linux 4.14
156 Document the SECCOMP_GET_ACTION_AVAIL operation added in Linux 4.14
158 Document the SECCOMP_FILTER_FLAG_LOG flag added in Linux 4.14
160 Document the SECCOMP_RET_LOG action added In Linux 4.14
161 Michael Kerrisk [Kees Cook]
162 Add description of SECCOMP_RET_KILL_PROCESS
164 Add SECCOMP_RET_KILL_THREAD description and rework SECCOMP_RET_KILL text
166 Document the seccomp audit logging feature added in Linux 4.14
171 Document the seccomp /proc interfaces added in Linux 4.14
172 Document the seccomp /proc interfaces in Linux 4.14:
173 /proc/sys/kernel/seccomp/actions_avail and
174 /proc/sys/kernel/seccomp/actions_logged.
177 Michael Kerrisk [Stas Sergeev]
178 Document the SS_AUTODISARM flag added in Linux 4.7
184 Document /proc/kpagecgroup
186 Add KPF_BALLOON, KPF_ZERO_PAGE, and KPF_IDLE for /proc/kpageflags
190 Document /proc/sys/kernel/ns_last_pid
193 New and changed links
194 ---------------------
196 pthread_spin_destroy.3
198 New link to new pthread_spin_init.3 page
200 pthread_spin_trylock.3
201 pthread_spin_unlock.3
203 New links to new pthread_spin_lock.3 page
211 Consistently use "x86-64", not "x86_64"
212 When referring to the architecture, consistently use "x86-64",
213 not "x86_64". Hitherto, there was a mixture of usages, with
214 "x86-64" predominant.
218 Replace incorrect uses of Latin abbreviation "cf.".
219 People seem to be using "cf." ("confere"), which means "compare",
220 to mean "see" instead, for which the Latin abbreviation would be
223 Changes to individual pages
224 ---------------------------
228 Clarify discussion of kernels that have no VFS capability support
232 clock_gettime() may be implemented in the vDSO
236 Warn that the clone() wrapper modifies child_stack in the parent
238 Rework the discussion of the historical CLONE_PID for clarity
242 Add a reference to new veth(4) page
244 Eliminate some redundant phrasing in discussion of "fn()"
246 Combine redundant paragraphs describing child_stack==NULL
248 Note that child_stack can be NULL when using the raw system call
250 Remove a redundant paragraph
254 Clarify that ECONNREFUSED is for stream sockets
257 Michael Kerrisk [Jens Axboe]
258 Inode read-write hints persist only until the filesystem is unmounted
262 Move NFS details to a headed subsection
263 Michael Kerrisk [Petr Uzel]
264 Placing an exclusive lock over NFS requires the file is open for writing
267 Rik van Riel [Colm MacCárthaigh, Michael Kerrisk]
268 Document effect of MADV_WIPEONFORK
275 Include <sys/types.h> in SYNOPSIS to obtain declaration of pid_t
283 getcpu() may have an implementation in the vDSO
287 Mention that PID == TGID, and note contrast with TID
289 SEE ALSO: add gettid(2)
292 Michael Kerrisk [Fabio Scotoni]
296 Michael Kerrisk [Scott Vokes]
297 Make it clear RLIMIT_NPROC is a limit on current number of processes
298 https://twitter.com/silentbicycle/status/893849097903505409
302 SEE ALSO: add getpid(2)
306 Note that gettimeofday() may be implemented in the vDSO
310 Rework version information for feature bits
314 Add iocb details to io_submit
315 Add more information about the iocb structure. Explains the
316 fields of the I/O control block structure which is passed to the
319 Add cross-reference to io_getevents(2)
321 Cross reference pwritev(2) in discussion of RWF_SYNC and RWF_DSYNC
325 Update example to take TSO into account
326 The existing example given specifically states that it focus on
327 x86 (TSO memory model), but gives a read-read vs write-write
328 ordering example, even though this scenario does not require
329 explicit barriers on TSO.
331 So either we change the example architecture to a weakly-ordered
332 architecture, or we change the example to a scenario requiring
335 Let's stay on x86, but provide a Dekker as example instead.
337 Adapt the MEMBARRIER_CMD_SHARED return value documentation to
338 reflect that it now returns -EINVAL when issued on a system
339 configured for nohz_full.
343 Note the limit for size of 'name'
346 Michael Kerrisk [Raghavendra D Prabhu]
347 ERRORS: document EINVAL error for invalid filename
351 Add explicit text noting that 'length' must be greater than 0
352 Currently, this detail is hidden in ERRORS. Make it clear in
355 SEE ALSO: add ftruncate(2)
358 Mike Kravetz [Florian Weimer, Jann Horn]
359 Add description of old_size == 0 functionality
360 Since at least the 2.6 time frame, mremap() would create a new
361 mapping of the same pages if 'old_size == 0'. It would also leave
362 the original mapping. This was used to create a 'duplicate
365 A recent change was made to mremap() so that an attempt to create a
366 duplicate a private mapping will fail.
367 Michael Kerrisk [Michal Hocko, Mike Kravetz]
368 BUGS: describe older behavior for old_size==0 on private mappings
369 Explain the older behavior, and why it changed. This is a
370 follow-up to Mike Kravetz's patch documenting the behavior
371 for old_size==0 with shared mappings.
373 Reformat EINVAL errors as a list
377 By contrast with O_RDONLY, no file permissions are required for O_PATH
378 Note one of the significant advantages of O_PATH: many of the
379 operations applied to O_PATH file descriptors don't require
380 read permission, so there's no reason why the open() itself
381 should require read permission.
383 Note use of O_PATH to provide O_EXEC functionality
385 Mention O_PATH file descriptor use with fexecve(3)
387 ERRORS: document EINVAL error for invalid filename
389 Clarify that O_TMPFILE creates a *regular* file
391 Make it explicit that O_CREAT creates a regular file
393 Since glibc 2.26, the open() wrapper always uses the openat() syscall
395 Change pathname used in discussion of rationale for openat()
396 /path/to/file is a little confusing as a pathname
398 Make the purpose of open() a little clearer at the start of the page
402 Clarifications needed due to NFS reexport
403 NeilBrown [Lennart Poettering]
404 Clarify MAX_HANDLE_SZ
405 As hinted in the kernel source, MAX_HANDLE_SZ is a hint
406 rather than a promise.
409 Michael Kerrisk [Marin H.]
410 Since Linux 4.5, fcntl() can be used to set O_DIRECT for a pipe
411 See https://bugzilla.kernel.org/show_bug.cgi?id=197917
415 SEE ALSO: add switch_root(8)
420 Currently pkey_alloc() syscall has two arguments, and the very
421 first argument is still not supported and should be set to zero.
422 The second argument is the one that should specify the
427 SEE ALSO: add ltrace(1)
430 Michael Kerrisk [Michał Zegan]
431 Fix bogus description of reboot() from non-initial PID namespace
432 The current text was confused (mea culpa). No signal is sent to
433 the init() process. Rather, depending on the 'cmd' given to
434 reboot(), the 'group_exit_code' value will set to either SIGHUP or
435 SIGINT, with the effect that one of those signals is reported to
436 wait() in the parent process.
438 See https://bugzilla.kernel.org/show_bug.cgi?id=195899
440 SEE ALSO: remove reboot(8) (synonym for halt(8)); add shutdown(8)
442 SEE ALSO: add systemctl(1), systemd(1)
447 Type fixes in SYNOPSIS
448 [mtk: The raw system calls use "unsigned int", but the glibc
449 wrappers have "int" for the 'flags' argument.]
453 SEE ALSO: add numactl(8)
456 Michael Kerrisk [Peter Zijlstra]
457 sched_yield() is intended for use with real-time scheduling policies
460 Michael Kerrisk [Adhemerval Zanella, Florian Weimer, Kees Cook]
461 Add some Caveats regarding the use of seccomp filters
463 Document the "default" filter return action
464 The kernel defaults to either SECCOMP_RET_KILL_PROCESS
465 or SECCOMP_RET_KILL_THREAD for unrecognized filter
466 return action values.
467 Michael Kerrisk [Kees Cook]
468 Change SECCOMP_RET_ACTION to SECCOMP_RET_ACTION_FULL
469 In Linux 4.14, the action component of the return value
470 switched from being 15 bits to being 16 bits. A new macro,
471 SECCOMP_RET_ACTION_FULL, that masks the 16 bits was added,
472 to replace the older SECCOMP_RET_ACTION.
474 Explicitly note that other threads survive SECCOMP_RET_KILL_THREAD
476 SEE ALSO: add strace(1)
479 Grégory Vander Schueren
480 Add EALREADY to ERRORS
484 SEE ALSO: add nsenter(1)
488 Note that return value of shmat() is page-aligned
492 Rework discussion of SA_SIGINFO handler arguments
493 Expand and rework the text a little, in particular adding
494 a reference to sigreturn(2) as a source of further
495 information about the ucontext argument.
497 Mention that libc sets the act.sa_restorer field
500 Michael Kerrisk [Walter Harms]
501 Reword BUGS text to be a little clearer
503 Add explicit error handling to example code
505 Add use of sigaction() to example code
509 Make it a little clearer that a stack frame is created by the kernel
511 glibc has a simple wrapper for sigreturn() that returns ENOSYS
515 Since Linux 2.6.31,'fd_in' and 'fd_out' may both refer to pipes
518 Michael Kerrisk [Richard Knutsson]
519 Use lstat() instead of stat()
520 It's more logical to use lstat() in the example code,
521 since one can then experiment with symbolic links, and
522 also the S_IFLNK case can also occur.
524 Correct AT_NO_AUTOMOUNT text and general revisions
525 Expand on the relationship between fstatat() and the other three
526 functions, and improve the description of AT_NO_AUTOMOUNT.
527 Specifically, both stat() and lstat() act the same way with
528 respect to automounts, and that behavior matches fstatat() with
529 the AT_NO_AUTOMOUNT flag.
533 Add some comments noting filesystems that are no longer current
535 Add comments describing a few filesystem types
539 Note that time() may be implemented in the vDSO
540 Michael Kerrisk [Victor Porton]
541 Language fix-up: clarify that "tasks" means "work"
542 See https://bugzilla.kernel.org/show_bug.cgi?id=197183
546 BUGS: document spurious UFFD_EVENT_FORK
551 NeilBrown [Jeff Layton]
552 Update description of error codes
553 Since 4.13, errors from writeback are more reliably reported
554 to all file descriptors that might be relevant.
556 Add notes to this effect, and also add detail about ENOSPC and
557 EDQUOT which can be delayed in a similar many to EIO - for NFS
562 Starting with glibc 2.27, abort() does not attempt to flush streams
564 SEE ALSO: add assert(3)
566 backtrace_symbols_fd(3)
567 Stefan Puiu [Walter Harms]
568 backtrace_symbols_fd() can trigger a call to malloc()
572 SEE ALSO: add daemon(7), logrotate(8)
576 Note use of errno(1) to look up error names and numbers
578 Update error list for POSIX.1-2008
579 POSIX.1-2008 specified a couple of new errors not present in
581 Michael Kerrisk [Walter Harms]
582 Note the use of perror(3) and strerror(3)
584 Recast the advice against manually declaring 'errno'
585 Recast the advice against manually declaring 'errno' to
586 a more modern perspective. It's 13 years since the original
587 text was added, and even then it was describing old behavior.
588 Cast the description to be about behavior further away in
589 time, and note more clearly that manual declaration will
590 cause problems with modern C libraries.
592 Add some missing errors
594 Error numbers are positive values (rather than nonzero values)
595 POSIX.1-2008 noted the explicitly the change (to align with
596 the C standards) that error numbers are positive, rather
599 Reorganize the text and and some subheadings
600 Restructure the text and add some subheadings for better
601 readability. No (intentional) content changes.
602 Michael Kerrisk [Wesley Aptekar-Cassels]
603 Note that error numbers vary somewhat across architectures
604 Added after a patch from Wesley Aptekar-Cassels that proposed
605 to add error numbers to the text.
607 Note the <errno.h> also provides the symbolic error names
608 Michael Kerrisk [Walter Harms]
609 Explicitly note that error numbers vary also across UNIX systems
613 glibc 2.24 dropped CWD from the default path
614 Document the glibc 2.24 change that dropped CWD from the default
615 search path employed by execlp(), execvp() and execvpe() when
620 O_PATH file descriptors are also usable with fexecve()
622 fexecve() is now implemented with execveat(2), where available
624 Add some detail on the glibc implementation of fexecve() via execveat(2)
628 glibc 2.27 relaxes the FTM requirements for ffsl() and ffsll()
632 SEE ALSO: add nproc(1)
635 Michael Kerrisk [David Eckardt]
636 Clarify that lround() rounds *halfway cases" away from zero
637 See https://bugzilla.kernel.org/show_bug.cgi?id=194601
641 glibc has deprecated exposing the definitions via <sys/types.h>
646 Remove reference to non-standard "tlpi_hdr.h" and replace calls to
647 functions that were declared in this header.
651 SEE ALSO: add valgrind(1)
655 Add a cross reference to Caveats in system(3)
656 All of the same risks regarding system() also apply to popen().
659 Michael Kerrisk [Rahul Bedarkar]
660 Improve sentence describing freeing of resources on process termination
661 As reported by Rahul, the existing sentence could be read as
662 meaning that resources of joined and terminated detached
663 threads are freed only at process termination. Eliminate
664 that possible misreading.
667 Michael Kerrisk [Peter Zijlstra]
668 pthread_yield() is intended for use with real-time scheduling policies
671 Michael Kerrisk [Křištof Želechovski]
672 The standards do not specify all of the locale categories
676 Fix cruft in code example
680 Use proper section cross references in function list
682 Remove crufty reference to pc(1)
686 Mention get_nprocs_conf(3)
687 Mention get_nprocs_conf(3) in discussion of _SC_NPROCESSORS_CONF
688 and _SC_NPROCESSORS_ONLN.
691 Michael Kerrisk [Bastien Roucaries]
692 Create a "Caveats" subsection to hold warnings about the use of system()
693 See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=882222
694 Michael Kerrisk [Bastien Roucaries]
695 Mention PATH explicitly in discussion of system() and set-UID programs
696 Michael Kerrisk [Bastien Roucaries]
697 Note that user input for system() should be carefully sanitized
699 Mention file capabilities in discussion of privileged programs
701 Correctly note which shell Debian uses as (noninteractive) /bin/sh
705 Add some notes on systemd and core dumps
707 Dumps are not produced if core_pattern is empty and core_uses_pid is 0
708 Michael Kerrisk [Per Böhlin]
709 RLIMIT_CORE is not enforced when piping core dump to a program
711 SEE ALO: add systemd-coredump(8)
713 SEE ALSO: add coredumpctl(1)
716 Michael Kerrisk [Jonny Grant]
717 Replace crufty URL reference for 'smb' with up-to-date URL
718 Michael Kerrisk [Jonny Grant]
719 Refer to VFAT as an extended FAT (not DOS) filesystem
722 Michael Kerrisk [Miklos Szered, Ram Pai]
723 Correct the description of the parent mount ID for /proc/PID/mountinfo
725 Add mmap-exclusive bit for /proc/[pid]/pagemap
727 Update description of /proc/<pid>/oom_score
729 Clarify permissions in /proc/[pid]/fd/
731 Add reference to pid_namespaces(7) for /proc/sys/kernel/ns_last_pid
735 SEE ALSO: add pam_shells(8)
739 Add a brief explanation of /sys/kernel
741 Add a brief description of /sys/class/net
743 Add a brief description of /sys/kernel/mm
745 Add brief description of /sys/kernel/debug/tracing
747 Add a description of /sys/kernel/mm/hugepages
751 SEE ALSO: add arpd(8)
755 Add a reference to xattr(7) in the discussion of extended attributes
757 SEE ALSO: add captest(8)
761 Note existence of kcmp() KCMP_EPOLL_TFD operation
765 Refer reader to pipe(7) for details of I/O semantics of FIFOs
769 SEE ALSO: add file-hierarchy(7)
773 SEE ALSO: add rdisc(8)
777 Note that "x86-64" is generally preferred over "x86_64"
779 Add a use case for real minus character
783 Add a reference to new veth(4) page
785 EXAMPLE: refer also to example in clone(2)
789 SEE ALSO: add reboot(2)
790 Add because reboot(2) has special semantics for non-initial
795 SEE ALSO: add pthread_spin_init(3) and pthread_spin_lock(3)
798 Michael Kerrisk [Petr Malat, Tobias Klausmann]
799 Correct the description of SO_RXQ_OVFL
803 SEE ALSO: add getconf(1), confstr(3), pathconf(3), sysconf(3)
806 Christian Brauner [Michael Kerrisk]
807 Document new 340 line idmap limit
810 Michael Kerrisk [Yubin Ruan]
811 Simplify language around conferring capabilities
812 The statement "conferring permitted or effective capabilities"
813 to the process is somewhat redundant. Binaries with capabilities
814 confer capabilities only to those process capability sets, so it's
815 simpler to just say "confers capabilities to the process".