Michael Kerrisk [Fri, 8 May 2015 11:13:03 +0000 (13:13 +0200)]
intro.1: Drop intro paragraph on '$?' shell variable
As Andries notes, this piece of text is rather out of place in
a page that was intended to provide a tutorial introduction for
beginners logging in on a Linux system.
Reported-by: Andries E. Brouwer <Andries.Brouwer@cwi.nl> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The "ABI" doesn't really convey anything significant in
the title. These subsections are about describing differences
between the kernel and (g)libc interfaces.
Reported-by: Andries E. Brouwer <Andries.Brouwer@cwi.nl> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
NeilBrown [Tue, 5 May 2015 22:59:07 +0000 (08:59 +1000)]
pty.7: Clarify asynchronous nature of PTY I/O
A PTY is not like a pipe - there may be delayed between data
being written at one end and it being available at the other.
This became particularly apparent after
commit f95499c3030f
("n_tty: Don't wait for buffer work in read() loop")
in Linux 3.12
See also the mail thread at https://lkml.org/lkml/2015/5/1/35
Date Mon, 04 May 2015 12:32:04 -0400
From Peter Hurley <>
Subject Re: [PATCH bisected regression] input_available_p()
sometimes says 'no' when it should say 'yes'
Reviewed-by: Peter Hurley <peter@hurleysoftware.com> Signed-off-by: NeilBrown <neilb@suse.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
get_mempolicy.2, set_mempolicy: Policy is per thread, not per process
set/get_mempolicy manpages say that the memory allocation
policy is per process while reading the code and testing shows
that it's actually per thread. Here's a quick fix, which may
need to be improved to better explain that we're allocating
in the context of a thread within a process address space.
Signed-off-by: Brice Goglin <Brice.Goglin@inria.fr> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Wed, 6 May 2015 16:20:41 +0000 (18:20 +0200)]
open.2: BUGS: O_CREAT | O_DIRECTORY succeeds if pathname does not exist
See http://www.openwall.com/lists/oss-security/2014/11/26/10
and http://thread.gmane.org/gmane.linux.file-systems/90997
Subject: O_CREAT|O_DIRECTORY on nonexisting file with ext4
not posix-compliant
Newsgroups: gmane.linux.file-systems
Date: 2014-12-15 17:39:09 GMT
and https://lkml.org/lkml/2005/9/23/80
Subject: [PATCH] open: O_DIRECTORY and O_CREAT together should fail
From: Miklos Szeredi <>
Date: Fri, 23 Sep 2005 16:45:04 +0200
Reported-by: NeilBrown <neilb@suse.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Wed, 6 May 2015 13:31:45 +0000 (15:31 +0200)]
ip.7: Relocate misplaced text describing ENOPROTOOPT error
Long ago, some page reworking moved this text to a somewhat
random location in the middle of the socket options list.
Move it to a sensible location, and at the same time,
rework the text to be a little clearer.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
To empirically verify the behaviour I took my test code from the
above page then changed it to use different values for the third
argument to socket() and the sll_protocol field:
- socket created with ETH_P_ARP, packet sent with ETH_P_ARP:
packet sent with EtherType of ETH_P_ARP
- socket created with ETH_P_ARP, sll_protocol==0:
packet sent with EtherType of 0
- socket created with 0x88b5, sll_protocol==htons(ETH_P_ARP):
packet sent with EtherType of ETH_P_ARP
- socket created with ETH_P_ARP, sll_protocol==htons(0x88b5):
packet sent with EtherType of 0x88b5
This shows that leaving sll_protocol set to zero does not have
the desired effect and that it needs to be set to the desired
link-layer protocol.
There is code in the relevant kernel source file
(net/packet/af_packet.c) which appears to inspect the value of the
sll_protocol field and use it as the link-layer protocol number,
however I am not sufficiently familiar with this subsystem to be
fully confident of what is happening. The line in question is:
proto = saddr->sll_protocol;
In version 3.4 of the kernel this can be found in the functions
packet_snd and tpacket_snd. In version 2.6.26 it is in packet_sendmsg.
Below is a patch that adds sll_protocol to the list of required fields.
This may not be the whole truth, since it is not clear what role if any
sll_protocol, sll_halen or sll_addr would play when the socket type is
SOCK_RAW, however I'm confident it is more accurate than the page as it
stands at present.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 5 May 2015 13:49:53 +0000 (15:49 +0200)]
proc.5: Document /proc mount options
Document the 'hidepid' and 'gid' mount options that were added in
Linux 3.3. See https://bugzilla.kernel.org/show_bug.cgi?id=90641
Based on text by Vasiliy Kulikov in
Documentation/filesystems/proc.txt.
Reported-by: Cameron Norman <camerontnorman@gmail.com> Cowritten-by: Vasiliy Kulikov <segooon@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 5 May 2015 10:12:35 +0000 (12:12 +0200)]
prctl.2: Note that "parent" for purposes of PR_SET_DEATHSIG is a *thread*
See https://bugzilla.kernel.org/show_bug.cgi?id=43300
Reported-by: David Wilcox <davidvsthegiant@gmail.com> Reported-by: Filipe Brandenburger <filbranden@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 5 May 2015 09:13:33 +0000 (11:13 +0200)]
sendfile.2: Note that sendfile does not support O_APPEND for 'out_fd'
See https://bugzilla.kernel.org/show_bug.cgi?id=82841 Reported-by: Jason Newton <nevion@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 5 May 2015 08:29:07 +0000 (10:29 +0200)]
cerf.3, cerfc.3, cerfcf.3, cerfcl.3, cerff.3. cerfl.3: Remove cerf(3) and links to it
These functions don't exist in glibc, aren't specified
in C99 or C11 (those standards merely reserve the names
for future use), cause package conflicts for libcerf
(http://apps.jcns.fz-juelich.de/doku/sc/libcerf),
which does provide implementations and man-pages for
these functions, and cause confusion for readers
who (not looking too closely at the page) wonder
where the glibc implementation is. Best to simply
remove this page and its links from man-pages.
Reported-by: Joachim Wuttke <j.wuttke@fz-juelich.de>
See https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=764310
and https://bugzilla.kernel.org/show_bug.cgi?id=80541
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Tue, 5 May 2015 08:08:03 +0000 (10:08 +0200)]
getopt.3: Remove crufty BUGS section
This piece of text in the man page is ancient (from
man-pages-1.20, circa 1998), and odd in the sense that it
describes a bug in POSIX that was (long ago) subsequently
fixed. As the standards committee noted, POSIX here seemed
to deviate from existing practice. The simplest fix is
to just remove this BUGS section.
See https://bugzilla.kernel.org/show_bug.cgi?id=90261
Reported-by: Guy Harris <guy@alum.mit.edu> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Carlos O'Donell [Fri, 1 May 2015 02:01:26 +0000 (22:01 -0400)]
gethostbyname.3: "order" is obsolete
>> +.BR resolv.conf(5),
>> +a local name server
>> .BR named (8),
>> a broken out line from \fI/etc/hosts\fP, and the Network
>> Information Service (NIS or YP), depending upon the contents of the
>> \fIorder\fP line in
>> .IR /etc/host.conf .
>
> Your patch didn't change the last few lines, but you may be able to
> help... Is the reference to "order" and /etc/host.conf on this page not
> obsolete by now. Looking at host.conf(5), one sees,
No, order *is* obsolete.
> Historical
> The nsswitch.conf(5) file is the modern way of controlling the
> order of host lookups.
>
> In glibc 2.4 and earlier, the following keyword is recognized:
>
> order This keyword specifies how host lookups are to be per‐
> formed. It should be followed by one or more lookup
> methods, separated by commas. Valid methods are bind,
> hosts, and nis.
>
> So, it looks like some fix is required here also. Right?
Yes. I didn't know how we wanted to talk about this particular topic.
The use of "order" is obsolete as of 2.5.
The following is a sketch of how I'd rewrite this to be more correct,
I'm out of time for today, but if you want to fix the formatting and
check it in that would be awesome.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Mon, 4 May 2015 14:45:34 +0000 (16:45 +0200)]
mmap.2: Remove text that implies that munmap() syncs MAP_SHARED mapping to file
The existing text in this page:
MAP_SHARED Share this mapping. Updates to the mapping
are visible to other processes that map this
file, and are carried through to the underly‐
ing file. The file may not actually be
updated until msync(2) or munmap() is called.
implies that munmap() will sync the mapping to the underlying
file. POSIX doesn't require this, and some light reading of the
code and some light testing (fsync() after munmap() of a large
file) also indicates that Linux doesn't do this.
Chris Metcalf [Mon, 4 May 2015 12:54:46 +0000 (14:54 +0200)]
CPU_SET.3: Clarify language about "available" cpus
The CPU_SET.3 man page uses the adjective "available" when
explaining what the argument to CPU_SET() means. This is
confusing, since "available" isn't well-defined. The kernel
has a set of adjectives (possible, present, online, and active)
that qualify cpus, but normally none of these are what the
cpu_set_t bit index means: it's just "which cpu", using the
kernel's internal numbering system, even if that cpu isn't
possible or present.
This change removes the word "available" and adds a sentence
warning that cpu sets may not be contiguous due to dynamic
cpu hotplug, etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Joern Heissler [Mon, 4 May 2015 12:44:49 +0000 (14:44 +0200)]
scanf.3: Improve description of %n specifier
The fscanf manpage contains this:
n Nothing is expected; instead, the number of characters
consumed thus far from the input is stored through the
next pointer, which must be a pointer to int. This is
not a conversion, although it can be suppressed with the
* assignment-suppression character. The C standard
says: "Execution of a %n directive does not increment
the assignment count returned at the completion of exe‐
cution" but the Corrigendum seems to contradict this.
Probably it is wise not to make any assumptions on the
effect of %n conversions on the return value.
posix manpages; all say that %n does *not* increase the counter.
%*n causes undefined behaviour according to c99+tc3. I wasn't
able to find proof that any Corrigendum says otherwise.
Therefore I think it's safe to say that you can indeed make the
assumption that %n does not affect the return value.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>