1 ==================== Changes in man-pages-3.80 ====================
3 Released: 2015-02-21, 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 Akihiro Motoki <amotoki@gmail.com>
14 Andy Lutomirski <luto@amacapital.net>
15 Bill McConnaughey <mcconnau@biochem.wustl.edu>
16 Chris Mayo <aklhfex@gmail.com>
17 Christophe Blaess <Christophe@blaess.fr>
18 David Wilson <dw@botanicus.net>
19 Denys Vlasenko <dvlasenk@redhat.com>
20 Doug Goldstein <cardoe@gentoo.org>
21 Eric Wong <normalperson@yhbt.net>
22 Heinrich Schuchardt <xypron.glpk@gmx.de>
23 J William Piggott <elseifthen@gmx.com>
24 James Hunt <james.hunt@ubuntu.com>
25 Jan Chaloupka <jchaloup@redhat.com>
26 Jan Stancek <jstancek@redhat.com>
27 Jeff Layton <jlayton@poochiereds.net>
28 Jens Thoms Toerring <jt@toerring.de>
29 Kevin Easton <kevin@guarana.org>
30 Luke Faraone <lfaraone@debian.org>
31 Mark Seaborn <mseaborn@chromium.org>
32 Mathieu Malaterre <malat@debian.org>
33 Michael Kerrisk <mtk.manpages@gmail.com>
34 Michal Hocko <mhocko@suse.cz>
35 Minchan Kim <minchan@kernel.org>
36 Patrick Horgan <phorgan1@gmail.com>
37 Peng Haitao <penght@cn.fujitsu.com>
38 Ralf Baechle <ralf@linux-mips.org>
39 Rob Somers <uberkermit@gmail.com>
40 Simon Paillard <spaillard@debian.org>
41 Stephen Smalley <sds@tycho.nsa.gov>
42 Tao Ma <tao.ma@oracle.com>
43 Tobias Herzke <tobias.linuxpatches.2014@gi2.herzkes.de>
44 Vince Weaver <vincent.weaver@maine.edu>
45 Vlastimil Babka <vbabka@suse.cz>
46 Zbigniew Brzeziński <zbigniew.brzezinski@student.put.poznan.pl>
48 Apologies if I missed anyone!
51 New and rewritten pages
52 -----------------------
55 Heinrich Schuchardt [Michael Kerrisk]
56 New man page for the ioctl(2) FAT API
57 The ioctl(2) system call may be used to retrieve information about
58 the FAT file system and to set file attributes.
62 Summary: this page has been significantly reorganised and rewritten
64 Recast discussion of 'advice' into two groups of values
65 madvise() is one of those system calls that has congealed over
66 time, as has the man page. It's helpful to split the discussion
67 of 'advice' into those flags into two groups:
69 * Those flags that are (1) widespread across implementations;
70 (2) have counterparts in posix_madvise(3); and (3) were present
71 in the initial Linux madvise implementation.
72 * The rest, which are values that (1) may not have counterparts
73 in other implementations; (2) have no counterparts in
74 posix_madvise(3); and (3) were added to Linux in more recent
77 Explicitly list the five flags provided by posix_fadvise()
78 Over time, bit rot has afflicted this page. Since the original
79 text was written many new Linux-specific flags have been added.
80 So, now it's better to explicitly list the flags that
81 correspond to the POSIX analog of madvise().
82 Jan Chaloupka [Hugh Dickins, Michael Kerrisk]
83 Starting with Linux 3.5, more file systems support MADV_REMOVE
85 Split EINVAL error into separate cases
87 Explain MADV_REMOVE in terms of file hole punching
89 MADV_REMOVE can be applied only to shared writable mappings
91 MADV_REMOVE cannot be applied to locked or Huge TLB pages
92 Michael Kerrisk [Vlastimil Babka]
93 Clarify that MADV_DONTNEED has effect on pages only if it succeeds
94 Michael Kerrisk [Vlastimil Babka]
95 Clarifications for MADV_DONTNEED
96 Michael Kerrisk [Michal Hocko]
97 Improve MADV_DONTNEED description
99 MADV_DONTNEED cannot be applied to Huge TLB or locked pages
100 Michael Kerrisk [Vlastimil Babka]
101 Remove mention of "shared pages" as a cause of EINVAL for MADV_DONTNEED
102 Michael Kerrisk [Vlastimil Babka]
103 Note Huge TLB as a cause of EINVAL for MADV_DONTNEED
104 Michael Kerrisk [Minchan Kim]
105 Add mention of VM_PFNMAP in discussion of MADV_DONTNEED and MADV_REMOVE
107 Drop sentence saying that kernel may ignore 'advice'
108 The sentence creates misunderstandings, and does not really
111 Note that some Linux-specific 'advice' change memory-access semantics
113 NOTES: Remove crufty text about "command" versus "advice"
114 The point made in this fairly ancient text is more or less evident
115 from the DESCRIPTION, and it's not clear what "standard" is being
118 Mention POSIX.1-2008 addition of POSIX_MADV_NOREUSE
120 Remove "POSIX.1b" from CONFORMING TO
122 Move mention of posix_fadvise() from CONFORMING TO to SEE ALSO
124 ERRORS: add EPERM error case for MADV_HWPOISON
126 Note that madvise() is nonstandard, but widespread
129 Newly documented interfaces in existing pages
130 ---------------------------------------------
134 (Briefly) document /proc/PID/attr/socketcreate
136 (Briefly) document /proc/PID/attr/keycreate
137 Michael Kerrisk [Stephen Smalley]
138 Document /proc/PID/attr/{current,exec,fscreate,prev}
139 Heavily based on Stephen Smalley's text in
140 https://lwn.net/Articles/28222/
141 From: Stephen Smalley <sds@epoch.ncsc.mil>
143 Subject: [RFC][PATCH] Process Attribute API for Security Modules
144 Date: 08 Apr 2003 16:17:52 -0400
146 Document /proc/sys/kernel/auto_msgmni
150 Document SO_REUSEPORT socket option
153 New and changed links
154 ---------------------
158 Make get_thread_area.2 a link to rewritten set_thread_area.2 page
161 Changes to individual pages
162 ---------------------------
166 Make option argument formatting consistent with other pages
170 Explain how access() check treats capabilities
171 We have users who are terribly confused why their binaries
172 with CAP_DAC_OVERRIDE capability see EACCESS from access() calls,
173 but are able to read the file.
175 The reason is access() isn't the "can I read/write/execute this
176 file?" question, it is the "(assuming that I'm a setuid binary,)
177 can *the user who invoked me* read/write/execute this file?"
180 That's why it uses real UIDs as documented, and why it ignores
181 capabilities when capability-endorsed binaries are run by non-root
182 (this patch adds this information).
184 To make users more likely to notice this less-known detail,
185 the patch expands the explanation with rationale for this logic
186 into a separate paragraph.
192 Improve TLS documentation
193 The documentation for set_thread_area was very vague. This
194 improves it, accounts for recent kernel changes, and merges
195 it with get_thread_area.2.
197 get_thread_area.2 now becomes a link.
199 While I'm at it, clarify the related arch_prctl.2 man page.
203 Update some portability details and bugs
205 Refer reader to BUGS in discussion of EINVAL error
209 Document V3 capabilities constants
211 Rewrite discussion of kernel versions that support file capabilities
212 File capabilities ceased to be optional in Linux 2.6.33.
216 Fix description of CLONE_PARENT_SETTID
217 CLONE_PARENT_SETTID only stores child thread ID in parent memory.
222 Document interaction of execve(2) with CLONE_FILES
223 This patch the fact that a successful execve(2) in a process that
224 is sharing a file descriptor table results in unsharing the table.
226 I discovered this through testing and verified it by source
227 inspection - there is a call to unshare_files() early in
231 Michael Kerrisk [Jeff Layton]
232 Clarify cases of conflict between traditional record and OFD locks
233 Verified by experiment on Linux 3.15 and 3.19rc4.
237 EAGAIN is not reported when task allocation fails
238 I am not sure why we have:
240 "EAGAIN fork() cannot allocate sufficient memory to copy
241 the parent's page tables and allocate a task structure
244 The text seems to be there from the time when man-pages
245 were moved to git so there is no history for it.
247 And it doesn't reflect reality: the kernel reports both
248 dup_task_struct and dup_mm failures as ENOMEM to the
249 userspace. This seems to be the case from early 2.x times
250 so let's simply remove this part.
252 Child and parent run in separate memory spaces
253 fork.2 should clearly point out that child and parent
254 process run in separate memory spaces.
256 NOTES: add "C library/kernel ABI differences" subheading
260 NOTES: add "C library/kernel ABI differences" subheading
264 Various rewordings plus one or two details clarified
266 Add pointer to example in listxattr(2)
270 NOTES: add "C library/kernel ABI differences" subheading
274 Provide example program
276 Reword discussion of size==0 case
278 Add note on handling increases in sizes of keys or values
280 Remove mention of which filesystems implement ACLs
281 Such a list will only become outdated (as it already was).
285 Document EFAULT and EINVAL errors
286 I encountered these errors while writing testcase for migrate_pages
287 syscall for LTP (Linux test project).
289 I checked stable kernel tree 3.5 to see which paths return these.
290 Both can be returned from get_nodes(), which is called from:
291 SYSCALL_DEFINE4(migrate_pages, pid_t, pid, unsigned long, maxnode,
292 const unsigned long __user *, old_nodes,
293 const unsigned long __user *, new_nodes)
295 The testcase does following:
297 a) old_nodes/new_nodes is area mmaped with PROT_NONE
298 b) old_nodes/new_nodes is area not mmapped in process address
299 space, -1 or area that has been just munmmaped
302 a) maxnodes overflows kernel limit
303 b) new_nodes contain node, which has no memory or does not exist
304 or is not returned for get_mempolicy(MPOL_F_MEMS_ALLOWED).
308 Overhaul the documentation
309 This clarifies the behavior and documents all four functions.
311 Clarify the lm bit's behavior
312 The lm bit should never have existed in the first place. Sigh.
316 Mention effect of READ_IMPLIES_EXEC personality flag
317 I puzzled over mprotect()'s effect on /proc/*/maps for a while
318 yesterday -- it was setting "x" without PROT_EXEC being specified.
319 Here is a patch to add some explanation.
323 Add details of MSGMNI default value
327 Clarify wording of MSGMAX and MSGMNB limits
331 Clarify PERF_EVENT_IOC_REFRESH behavior
332 Currently the PERF_EVENT_IOC_REFRESH ioctl, when applied to a group
333 leader, will refresh all children. Also if a refresh value of 0
334 is chosen then the refresh becomes infinite (never runs out).
335 Back in 2011 PAPI was relying on these behaviors but I was told
336 that both were unsupported and subject to being removed at any time.
337 (See https://lkml.org/lkml/2011/5/24/337 )
338 However the behavior has not been changed.
340 This patch updates the manpage to still list the behavior as
341 unsupported, but removes the inaccurate description of it
342 only being a problem with 2.6 kernels.
345 Michael Kerrisk [Bill McConnaughey]
346 Mention file capabilities in discussion of PR_SET_DUMPABLE
348 Greatly expand discussion of "dumpable" flag
349 In particular, detail the interactions with
350 /proc/sys/fs/suid_dumpable.
352 Reorder paragraphs describing PR_SET_DUMPABLE
354 Mention SUID_DUMP_DISABLE and SUID_DUMP_USER under PR_SET_DUMPABLE
356 Executing a file with capabilities also resets the parent death signal
360 Explain behaviour should ptrace tracer call execve(2)
361 This behaviour was verified by reading the kernel source and
362 confirming the behaviour using a test program.
364 Add information on PTRACE_SEIZE versus PTRACE_ATTACH differences
365 Extend description of PTRACE_SEIZE with the short summary of its
366 differences from PTRACE_ATTACH.
368 The following paragraph:
371 Stop induced by PTRACE_INTERRUPT command, or group-stop, or ini-
372 tial ptrace-stop when a new child is attached (only if attached
373 using PTRACE_SEIZE), or PTRACE_EVENT_STOP if PTRACE_SEIZE was used.
375 has an editing error (the part after last comma makes no sense).
378 Mention that legacy post-execve SIGTRAP is disabled by PTRACE_SEIZE.
381 Michael Kerrisk [Christophe Blaess]
382 SYNOPSIS: remove 'const' from 'attr' sched_getattr() argument
386 Note default value for SEMMNI and SEMMSL
390 Note defaults for SEMOPM and warn against increasing > 1000
394 Caution against modifying sent pages
398 ERRORS: add ENOTSUP for invalid namespace prefix
400 Remove redundant text under ENOTSUP error
402 Note that zero-length attribute values are permitted
404 Rework text describing 'flags' argument
408 NOTES: add "C library/kernel ABI differences" subheading
411 Michael Kerrisk [Jan Chaloupka]
412 Document the 'f_flags' field added in Linux 2.6.36
414 Clarify that 'statfs' structure has some padding bytes
415 The number of padding bytes has changed over tyme, as some
416 bytes are used, so describe this aspect of the structure
419 Add OCFS2_SUPER_MAGIC
421 Use __fsword_t in statfs structure definition
422 This more closely matches modern glibc reality.
424 Add a note on the __fsword_t type
426 Document 'f_spare' more vaguely
430 Note that waitpid() is a wrapper for wait4()
432 Note that wait() is a library function implemented via wait4()
436 NOTES: add "C library/kernel ABI differences" subheading
441 I (and some others) found that the original example code
442 did not seem to work as advertised. The new code (used by
443 permission of the original author, Jens Thoms Toerring)
444 was found on comp.os.linux.development.
448 DESCRIPTION reference to BUGS corrected
449 mktemp(3)'s DESCRIPTION referenced NOTES, but no such
450 section exists. Corrected to refer to BUGS.
452 pthread_attr_setschedparam.3
454 Describe EINVAL in ERRORS
459 host.conf 'order' option deprecated, replaced by nsswitch.conf(5)
460 http://www.sourceware.org/bugzilla/show_bug.cgi?id=2389
461 http://repo.or.cz/w/glibc.git/commit/b9c65d0902e5890c4f025b574725154032f8120a
463 Reported at http://bugs.debian.org/270368,
464 http://bugs.debian.org/396633, and http://bugs.debian.org/344233.
468 Document missing 'f_flag' bit values
469 And reorganize information relating to which flags are in
471 Michael Kerrisk [Jan Chaloupka]
472 statvfs() now populates 'f_flag' from statfs()'s f_flag field
473 These changes came with glibc 2.13, and the kernel's addition of
474 a 'f_flags' field in Linux 2.6.36.
477 Michael Kerrisk [Doug Goldstein]
478 Remove unneeded <stdarg.h>
479 vsyslog() does not need this.
484 tzset.3 does not illustrate the POSIX offset format.
485 Specifically, there is no indication in the manual
486 what the optional components of it are.
490 Note maximum number of bytes returned by read(2) on /dev/random
491 Michael Kerrisk [Mathieu Malaterre]
492 Since Linux 3.16, reads from /dev/urandom return at most 32 MB
493 See https://bugs.debian.org/775328 and
494 https://bugzilla.kernel.org/show_bug.cgi?id=80981#c9
497 Michael Kerrisk [Bill McConnaughey]
498 Executing a file that has capabilities also prevents core dumps
500 Document "%i" and "%I" core_pattern specifiers
504 Remove words "and protocols"
505 There are no protocol descriptions in Section 5. Protocols are
510 Add reference to prctl(2) in discussion of /proc/sys/fs/suid_dumpable
511 And note that /proc/sys/fs/suid_dumpable defines the
512 value assigned to the process "dumpable" flag in certain
515 Note that CAP_SYS_ADMIN is required to list /proc/PID/map_files
516 This might however change in the future; see the Jan 2015 LKML thread:
518 Re: [RFC][PATCH v2] procfs: Always expose /proc/<pid>/map_files/
523 SEE ALSO: add nsswitch.conf(5)
527 Mention SECBIT_KEEP_CAPS as an alternative to prctl() PR_SET_KEEPCAPS
529 NOTES: add last kernel versions for obsolete options
530 The CONFIG_SECURITY_CAPABILITIES option was removed by
531 commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27
533 The CONFIG_SECURITY_FILE_CAPABILITIES option removed in
534 Linux 2.6.33 as already mentioned in DESCRIPTION.
538 SEE ALSO: add fork(2)
542 Add some details for SO_REUSEPORT
546 Mention SOCK_STREAM socket for ioctl_type of ioctl()
547 from https://bugzilla.redhat.com/show_bug.cgi?id=1110401.
549 unix.7 is not clear about socket type of ioctl_type argument of
550 ioctl() function. The description of SIOCINQ is applicable only
551 for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives
552 correct description of SIOCINQ
556 Place options in alphabetical order
558 Note glibc version number for '-l' option
560 Document -c/--format option
562 Add long form of some options
563 Michael Kerrisk [Patrick Horgan]
564 ld.so.conf uses only newlines as delimiters
565 mtk: confirmed by reading source of parse_conf() in
568 Document -V/--version option
570 Document -i/--ignore-aux-cache option
574 Relocate "Hardware capabilities" to be a subsection under notes
575 This is more consistent with standard man-pages headings
578 (Briefly) document LD_TRACE_PRELINKING
580 Remove duplicate description of LD_BIND_NOT
projects / thirdparty / man-pages.git / blob