1 ==================== Changes in man-pages-4.09 ====================
3 Released: ????-??-??, Munich
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 Afzal Mohammed <afzal.mohd.ma@gmail.com>
14 Andrew Clayton <andrew@digital-domain.net>
15 Carlos O'Donell <carlos@redhat.com>
16 Christoph Lameter <cl@linux.com>
17 Daniel Baluta <daniel.baluta@gmail.com>
18 Daniel Berrange <berrange@redhat.com>
19 Daniel Wagner <wagi@monom.org>
20 Darrick J. Wong <darrick.wong@oracle.com>
21 Dave Hansen <dave.hansen@intel.com>
22 Dmitry V. Levin <ldv@altlinux.org>
23 Dr. Tobias Quathamer <toddy@debian.org>
24 Elliott Hughes <enh@google.com>
25 Eric W. Biederman <ebiederm@xmission.com>
26 Eugene Syromyatnikov <evgsyr@gmail.com>
27 Florian Weimer <fweimer@redhat.com>
28 Heinrich Schuchardt <xypron.glpk@gmx.de>
29 Igor Liferenko <igor.liferenko@gmail.com>
30 Jakub Wilk <jwilk@jwilk.net>
31 Jann Horn <jann@thejh.net>
32 Jeremy Harris <jgh@redhat.com>
33 Kees Cook <keescook@chromium.org>
34 Keno Fischer <keno@juliacomputing.com>
35 Laurent Georget <laurent.georget@supelec.fr>
36 Laurent Georget <laurent@lgeorget.eu>
37 Marcos Mello <marcosfrm@gmail.com>
38 Michael Hausenblas <michael.hausenblas@gmail.com>
39 Michael Kerrisk <mtk.manpages@gmail.com>
40 Mike Frysinger <vapier@gentoo.org>
41 Mike Galbraith <efault@gmx.de>
42 Miroslav Koskar <mk@mkoskar.com>
43 Nikos Mavrogiannopoulos <nmav@redhat.com>
44 Omar Sandoval <osandov@fb.com>
45 Pavel Emelyanov <xemul@virtuozzo.com>
46 Piotr Kwapulinski <kwapulinski.piotr@gmail.com>
47 Siddhesh Poyarekar <siddhesh@sourceware.org>
48 Theodore Ts'o <tytso@mit.edu>
49 Vegard Nossum <vegard.nossum@oracle.com>
50 Vincent Lefevre <vincent@vinc17.net>
51 Vince Weaver <vincent.weaver@maine.edu>
52 Wainer dos Santos Moschetta <wainersm@linux.vnet.ibm.com>
53 Wang Long <long.wanglong@huawei.com>
54 Willy Tarreau <w@1wt.eu>
55 Zack Weinberg <zackw@panix.com>
57 Apologies if I missed anyone!
60 New and rewritten pages
61 -----------------------
64 Dave Hansen [Michael Kerrisk]
65 New page documenting pkey_alloc(2) and pkey_free(2)
67 pthread_getattr_default_np.3
69 New page documenting pthread_getattr_default_np(3) and pthread_setattr_default_np(3)
72 Wainer dos Santos Moschetta
73 New page documenting strfromd(3), strfromf(3), and strfroml(3)
74 The ISO/IEC TS 18661-1 specifies the strfrom() class
75 of functions that convert a float-point value to string.
78 Keno Fischer [Michael Kerrisk]
79 New page describing /dev/fuse
80 This is my writeup of a basic description of /dev/fuse after
81 playing with it for a few hours today. It is of course woefully
82 incomplete, and since I neither have a use case nor am working
83 on this code, I will not be in a position to expand it in the
84 near future. However, I'm hoping this could still serve as a
85 handy reference for others looking at this interface.
87 [mtk: Notwithstanding the incompleteness of this page,
88 it's a good base for future extension.]
92 New page documenting the tmpfs filesystem
95 Dave Hansen [Michael Kerrisk]
96 New page with overview of Memory Protection Keys
99 Michael Kerrisk [Theodore Ts'o, Nikos Mavrogiannopoulos, Laurent Georget]
100 New page providing an overview of interfaces for obtaining randomness
101 Contains material extracted from getrandom(2) and random(4),
102 as well as new material.
105 Pavel Emelyanov, Dmitry V. Levin
106 New page documenting NETLINK_SOCK_DIAG interface
118 These pages also saw substantial updates, as described under
119 "Changes to individual pages".
122 Newly documented interfaces in existing pages
123 ---------------------------------------------
127 Add (much) more detail on MAP_GROWSDOWN
131 Document the new pkey_mprotect() system call
133 Document PROT_SEM, PROT_SAO, PROT_GROWSUP, and PROT_GROWSDOWN
137 Document PR_SET_FP_MODE and PR_GET_FP_MODE
141 PERF_RECORD_SWITCH support
142 Linux 4.3 introduced two new record types for recording context
143 switches: PERF_RECORD_SWITCH and PERF_RECORD_SWITCH_CPU_WIDE.
145 Add PERF_SAMPLE_BRANCH_CALL branch sample type
147 PERF_SAMPLE_BRANCH_IND_JUMP branch_sample_type
148 Linux 4.2 added a new branch_sample_type: PERF_SAMPLE_BRANCH_IND_JUMP
150 Document PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT
152 Document sample_max_stack and /proc/sys/kernel/perf_event_max_stack
153 Linux 4.8 added a new sample_max_stack parameter, as well as
154 /proc/sys/kernel/perf_event_max_stack which limits it and a new
155 EOVERFLOW error return.
157 PERF_RECORD_LOST_SAMPLES record type
158 Linux 4.2 added a new record type: PERF_RECORD_LOST_SAMPLES
159 It is generated when hardware samples (currently only Intel PEBS)
164 Document PTRACE_SECCOMP_GET_FILTER
166 Document PTRACE_GET_THREAD_AREA and PTRACE_SET_THREAD_AREA
169 Michael Kerrisk [Eric W. Biederman]
170 Document the NS_GET_USERNS and NS_GET_PARENT ioctl() operations
173 Michael Kerrisk [Mike Galbraith]
174 Document the autogroup feature
175 Includes documenting autogroup nice value
177 Autogrouping breaks traditional semantics of nice in many cases
178 When autogrouping is enabled (the default in many distros)
179 there are many traditional use cases where the nice value
180 ceases to have any effect.
182 Add a subsection on nice value and group scheduling
185 New and changed links
186 ---------------------
190 New link to relocated killpg(3) page
194 New link to new pkey_alloc(2) page
198 New link to mprotect(2)
200 pthread_setattr_default_np.3
202 New link to new pthread_getattr_default_np.3
205 Wainer dos Santos Moschetta
206 New link to strfromd(3)
209 Wainer dos Santos Moschetta
210 New link to strfromd(3)
218 Remove ancient libc4 and libc5 details
219 It's nearly 20 years now since Linux libc went away.
220 Remove some ancient details from the pages.
224 Add cross references to new tmpfs(5) page
228 Change section number from 2 to 3 in killpg() references
231 Changes to individual pages
232 ---------------------------
236 Remove editorializing comments about 'socklen_t'
238 Simplify the discussion of 'socklen_t'
239 We don't really need to list the old OSes in this discussion.
245 SEE ALSO: add hwclock(8)
253 Replace discussion of 'socklen_t' with reference to accept(2)
254 The discussion of 'socklen_t' editorializes and is repeated
255 across several pages. Replace it with a reference to accept(2),
256 where some details about this type are provided.
260 SEE ALSO: add chmod(1)
264 SEE ALSO: add chgrp(1) and chown(1)
268 SEE ALSO: add chroot(1)
272 The CLONE_*_SETTID operations store TID before return to user space
273 CLONE_PARENT_SETTID and CLONE_CHILD_SETTID store the new
274 TID before clone() returns to user space
277 Michael Kerrisk [Daniel Wagner]
278 Rework and greatly extend discussion of error handling
279 Further clarify that an error return should be used only
280 for diagnostic or remedial purposes.
282 Other UNIX implementations also close the FD, even if reporting an error
283 Looking at some historical source code suggests
284 that the "close() always closes regardless of error return"
285 behavior has a long history, predating even POSIX.1-1990.
287 Note that future POSIX plans to require that the FD is closed on error
288 See http://austingroupbugs.net/view.php?id=529#c1200.
290 Clarify the variation in EINTR behavior per POSIX and other systems
294 Document behavior with shared blocks
295 Note that FALLOC_FL_UNSHARE may use CoW to unshare blocks to
296 guarantee that a disk write won't fail with ENOSPC.
300 Mention FAN_Q_OVERFLOW
301 To receive overflow events it is necessary to set this bit
306 F_GETPIPE_SZ allocates next power-of-2 multiple of requested size
307 Add some detail about current implementation, since this helps
308 the user understand the effect of the user pipe limits added in
309 Linux 4.5 (described in pipe(7)).
311 Add EPERM that occurs for F_SETPIPE_SZ when user pipe limit is reached
314 Darrick J. Wong [Omar Sandoval]
315 Fix the discussion of maximum sizes
316 Fix the discussion of the limitations on the dest_count and
317 src_length parameters to the fideduperange ioctl() to reflect
318 what's actually in the kernel.
322 SEE ALSO: add fileno(3)
323 fileno(3) is useful if one is combining fflush(3)/fclose(3)
326 SEE ALSO: add fflush(3)
330 FTM requirements fix for setgroups(2)
334 SEE ALSO: add hostname(1)
338 Note that 'addr' must be NULL when 'flags' is 0
342 Warn that autogrouping voids the effect of 'nice' in many cases
343 Refer the reader to sched(7) for the details.
345 Expand discussion of getpriority() return value
347 The nice value supplied to setpriority() is clamped
348 Note that the nice value supplied to setpriority() is clamped
349 to the permitted range.
351 Improve description of setpriority() return value
356 Move nice value details from getpriority(2) to sched(7)
357 Centralizing these details in sched(7) is more logical.
362 Consolidate and improve discussion on usage of randomness
363 Currently, recommendations on how to consume randomness are
364 spread across both getrandom(2) and random(4) and the general
365 opinion seems to be that the text in getrandom(2) does a
366 somewhat better job. Consolidate the discussion to a single
367 page (getrandom(2)) and address some of the concerns
368 expressed about the existing text in random(4).
369 [Some of this text ultimately made its way into the new
374 Remove material incorporated into random(7)
376 Note advantages of fact that getrandom() doesn't use file descriptors
378 Clarify that getrandom() is not "reading" from /dev/{random,urandom}
382 Refer to sched(7) in discussion of RLIMIT_RTPRIO and RLIMIT_RTTIME
384 Describe the range of the RLIMIT_NICE limit
386 Refer to sched(7) in the discussion of RLIMIT_NICE
388 SEE ALSO: add credentials(7)
391 ioctl_fideduperange.2
393 Clarify the behavior of the FIDEDUPERANGE ioctl
397 SEE ALSO: add kill(1)
400 Michael Kerrisk [Christoph Lameter]
401 Memory policy is a per-thread attribute, not a per-process attribute
405 Piotr Kwapulinski [Christoph Lameter, Michael Kerrisk]
406 Add MPOL_LOCAL NUMA memory policy documentation
410 SEE ALSO: add mountpoint(1)
414 CONFORMING TO: note that pkey_mprotect() is Linux-specific
418 Warn that autogrouping voids the effect of 'nice' in many cases
420 CONFORMING TO: Remove an ancient SVr4 detail on errno values
422 Rework discussion of nice() return value and standards conformance
423 Make the text a little clearer. In particular, clarify that the
424 raw system call (still) returns 0 on success.
426 Clarify the range of the nice value, and note that it is clamped
428 Add mention of RLIMIT_NICE
430 Move discussion of handling the -1 success return to RETURN VALUE
431 This detail was rather hidden in NOTES. Also, rework the text
434 Clarify that nice() changes the nice value of the calling *thread*
436 Add "C library/kernel differences" subsection heading
438 Add reference to sched(7) for further details on the nice value
442 ubifs supports O_TMPFILE starting with Linux 4.9
444 Document ENOMEM that occurs when opening FIFO because of pipe hard limit
448 Add cycles field in LBR records
449 Linux 4.3 added a cycles field to the PERF_SAMPLE_BRANCH_STACK
452 Update time_shift sample code
453 Linux 4.3 improved the accuracy of the clock/ns conversion routines.
455 Clarify the use of signals for capturing overflow events
459 Add ENFILE error for user pipe hard limit reached
463 Some additional details regarding the PR_GET_UNALIGNED operation
465 Note the output buffer size for PR_GET_TID_ADDRESS operation on x32/n32
467 Remove numeric definitions of PR_FP_MODE_FR and PR_FP_MODE_FRE bits
471 Document the behavior of PTRACE_SYSEMU stops
473 Expand documentation PTRACE_EVENT_SECCOMP traps
474 In Linux 4.8, the order of PTRACE_EVENT_SECCOMP and
475 syscall-entry-stops was reversed. Document both behaviors and
476 their interaction with the various forms of restart.
480 Describe Q_XQUOTASYNC, which is present but no-op in recent kernels
484 Note errors for invalid commands inside a PID namespace
488 Fix cross reference for further info on the nice value
489 The information moved from getpriority(2) to sched(7).
492 Michael Kerrisk [Daniel Berrange]
493 Mention SCHED_DEADLINE
494 Give the reader a clue that there is another policy
495 available that can't be set via sched_setscheduler(2).
499 Document changed interaction with ptrace
500 Before kernel 4.8, the seccomp check will not be run again
501 after the tracer is notified. Fixed in kernel 4.9.
503 NOTES: mention ptrace(PTRACE_SECCOMP_GET_FILTER) to dump seccomp filters
507 Reformat list of modes
511 Improve wording of text on calling setsid() after fork()+_exit()
513 SEE ALSO: add sched(7)
514 List sched(7), because setsid(2) is part of the machinery
519 Further documentation of SEGV_PKUERR
523 Document ssi_addr_lsb field of signalfd_siginfo
527 SEE ALSO: add namei(1)
531 Fix description for ESPIPE error
532 A file descriptor can't refer to a symbolic link.
536 Add pkey_alloc(), pkey_free(), and pkey_mprotect()
537 New system calls in Linux 4.9.
539 Add ppc_swapcontext(2)
543 Document CLOCK_BOOTTIME
545 Document CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM
549 Document CLOCK_BOOTTIME, CLOCK_REALTIME_ALARM, and CLOCK_BOOTTIME_ALARM
551 Document TFD_TIMER_CANCEL_ON_SET
553 Rework discussion on relative and absolute timers
557 SEE ALSO: add unlink(2)
562 SEE ALSO: add touch(1)
566 On some architectures, waitpid() is a wrapper that calls wait4().
569 Wainer dos Santos Moschetta
570 SEE ALSO: add strfromd(3)
576 RETURN VALUE: describe return values more explicitly
579 Michael Kerrisk [Igor Liferenko]
580 Add glibc error text for EILSEQ
585 SEE ALSO: add fileno(2)
589 Remove deprecated _REENTRANT from FTM requirements for getlogin_r()
591 SEE ALSO: add logname(1)
595 Note circumstances where 'c' must be cast to 'unsigned char'
599 Move killpg.2 from section to to section 3
602 Michael Kerrisk [Siddhesh Poyarekar]
603 Document 0 as default value of M_ARENA_MAX and explain its meaning
605 Improve description of M_ARENA_TEST
607 Document default value for M_ARENA_TEST
609 Note default value of M_PERTURB
612 Michael Kerrisk [Igor Liferenko]
613 Note behavior of mbsnrtowcs() for an incomplete character
614 Note the behavior of mbsnrtowcs() when an incomplete character
615 is found at end of the input buffer.
619 Michael Kerrisk [Igor Liferenko]
620 Improve language relating to "initial state"
621 See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839705
624 Michael Kerrisk [Igor Liferenko]
625 Add missing include to example program
626 See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=845172
630 DESCRIPTION: add reference to mq_notify(3)
634 Clarification regarding usage of mq_flags attribute in mq_open()
639 Clarification regarding reasons behind EBADF
642 Wainer dos Santos Moschetta
643 SEE ALSO: add strfromd(3)
647 SEE ALSO: add pthread_setattr_default_np(3)
651 SEE ALSO: add pthread_setattr_default_np(3)
655 Note that ptsname_r() is proposed for future inclusion in POSIX.1
657 CONFORMING TO:: clarify that only ptsname() is standardized (so far)
661 Note fix to remainder(nan(""), 0) handling
662 The bug https://www.sourceware.org/bugzilla/show_bug.cgi?id=6779
663 has been fixed in glibc 2.15.
665 Document fixes for EDOM handling for range errors
666 The bug http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783
667 was fixed in glibc 2.15.
671 _BSD_SOURCE must be *explicitly* defined to get BSD setjmp() semantics
674 Wainer dos Santos Moschetta
675 SEE ALSO: add strfromd(3)
679 Document fixes to give ERANGE for underflow range error
680 The bug https://www.sourceware.org/bugzilla/show_bug.cgi?id=6810
681 was fixed in glibc 2.19.
686 Michael Kerrisk [Vincent Lefevre]
687 Add RETURN VALUE section
691 Properly document tmpnam_r(3)
695 Note circumstances where 'c' must be cast to 'unsigned char'
703 Add brief descriptive text for KDGKBMODE modes
705 Add K_OFF keyboard mode
709 Add reference to new random(7) page
711 Rework formatting of /proc interfaces
712 Make the information easier to parse by formatting the file
713 descriptions as hanging lists. No significant content changes.
714 Nikos Mavrogiannopoulos [Laurent Georget]
715 Provide a more accurate description of /dev/urandom
716 This documents the "property" of /dev/urandom of being able to
717 serve numbers prior to pool being initialized, and removes any
718 suggested usages of /dev/random which are disputable
719 (i.e., one-time pad). Document the fact /dev/random is only
720 suitable for applications which can afford indeterminate delays
721 since very few applications can do so. Smooth the alarming
722 language about a theoretical attack, and mention that its
723 security depends on the cryptographic primitives used by the
724 kernel, as well as the total entropy gathered.
725 Michael Kerrisk [Laurent Georget, Theodore Ts'o]
726 Improve discussion of /dev/urandom, blocking reads, and signals
727 The text currently states that O_NONBLOCK has no effect for
728 /dev/urandom, which is true. It also says that reads from
729 /dev/urandom are nonblocking. This is at the least confusing.
730 If one attempts large reads (say 10MB) from /dev/urandom
731 there is an appreciable delay, and interruption by a signal
732 handler will result in a short read. Amend the text to
737 Add subsection headers at major points
738 The current pages dumps all the content into one big DESCRIPTION
739 with no real visual break up between logically independent
740 sections. Add some subsection headers to make it easier to
744 Document the Elf{32,64}_Nhdr structure, the sections/segments that
745 contain notes, and how to interpret them. I've been lazy and only
746 included the GNU extensions here, especially as others are not
747 defined in the elf.h header file as shipped by glibc.
751 SEE ALSO: add fuse(4)
755 Describe new ProtectionKey 'smaps' field
757 Add example ProtectionKey output for 'smaps' file
759 Add pointers to sched(7) for autogroup files
760 sched(7) describes /proc/sys/kernel/sched_autogroup_enabled
761 and /proc/PID/autogroup.
763 Add /proc/sys/fs/pipe-user-pages-{hard,soft} entries
765 Improve description of the KernelPageSize and MMUPageSize 'smaps' fields
767 Rework 'smaps' ProtectionKey text and add some details
769 Mention lslocks(8) in discussion of /proc/locks
771 Describe Shmem field of /proc/meinfo
773 Rework 'smaps' VmFlags text, and add kernel version and example output
778 Move /proc/sys/fs/pipe-max-size content from proc(5) to pipe(7)
781 Carlos O'Donell [Florian Weimer]
782 Timeout does not map to resolver API calls
786 SEE ALSO: add users(1)
790 CAP_SYS_ADMIN governs ptrace(2) PTRACE_SECCOMP_GET_FILTER
792 CAP_SYS_ADMIN allows privileged ioctl() operations on /dev/random
796 Add details on 'cpu' CFS bandwidth control
800 SEE ALSO: add setpriv(1)
802 SEE ALSO: add shadow(5)
804 feature_test_macros.7
805 Michael Kerrisk [Zack Weinberg]
806 Note that _REENTRANT and _THREAD_SAFE are now deprecated
808 Note that "cc -pthread" defines _REENTRANT
812 Note a subtlety of event generation when monitoring a directory
816 Add a note on why glibc 2.x uses the soname libc.so.6
818 Add a few historical details on Linux libc4 and libc5
819 Just for historical interest. Details taken from
820 http://www.linux-m68k.org/faq/glibcinfo.html.
824 Add a cross-reference to groff_mdoc(7)
828 SEE ALSO: add user_namespaces(7)
833 Migrate subsection on mount restrictions to mount_namespaces(7)
834 This section material in the user_namespaces(7) page was written
835 before the creation of the mount_namespaces(7) manual page.
836 Nowadays, this material properly belongs in the newer page.
840 Document NETLINK_INET_DIAG rename to NETLINK_SOCK_DIAG
842 Add references to sock_diag(7)
846 Refer to namespaces(7) for information about NS_GET_PARENT
849 Michael Kerrisk, Vegard Nossum [Vegard Nossum]
850 Document /proc files controlling memory usage by pipes
851 Document /proc/sys/fs/pipe-max-size and
852 /proc/sys/fs/pipe-user-pages-{soft,hard}.
854 Document pre-Linux 4.9 bugs in pipe limit checking
858 Add a new introductory paragraph describing the nice value
860 Add more precise details on CFS's treatment of the nice value
862 Mention RLIMIT_NICE in the discussion of the nice value
864 NOTES: mention cgroups CPU controller
866 Add introductory sentence mentioning CFS scheduler
868 Add nice(2), getpriority(2), and setpriority(2) to API list
870 Make it clearer that SCHED_OTHER is always scheduled below real-time
872 Give the page a more generic NAME
873 The page isn't just about APIs.
877 POSIX.1-2016 (POSIX.1-2008 TC2) has now been released
881 SEE ALSO: add namei(1)
885 Use "example.com" as example domain
889 Add reference to namespaces(7) for NS_GET_USERNS operation
891 Add reference to namespaces(7) for NS_GET_PARENT operation