Commit Graph

12519 Commits

Author SHA1 Message Date
Michael Kerrisk 8ce45022bb ld.so.8: Relocate "Hardware capabilities" to be a subsection under notes
This is more consistent with standard man-pages headings
and layout.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Michael Kerrisk f794d5274f capabilities.7: srcfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Michael Kerrisk 6016943675 capabilities.7: Minor tweaks
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Chris Mayo 16512b57bc capabilities.7: NOTES: add last kernel versions for obsolete options
The CONFIG_SECURITY_CAPABILITIES option was removed by
commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27

The CONFIG_SECURITY_FILE_CAPABILITIES option removed in
Linux 2.6.33 as already mentioned in DESCRIPTION.

Signed-off-by: Chris Mayo <aklhfex@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Michael Kerrisk 11af2d4b98 socket.7: Add some details for SO_REUSEPORT
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Michael Kerrisk c28f1dd3ec socket.7: Minor fixes
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
David Wilson 75979920fe socket.7: Document SO_REUSEPORT socket option
Signed-off-by: David Wilson <dw@botanicus.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
James Hunt 674f11ecbc ptrace.2: Explain behaviour should ptrace tracer call execve(2)
This behaviour was verified by reading the kernel source and
confirming the behaviour using a test program.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Michael Kerrisk ca12634681 pthread_attr_setschedparam.3: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Tobias Herzke 3f6dadab7b pthread_attr_setschedparam.3: Describe EINVAL in ERRORS
The following example proves that the man page
pthread_attr_setschedparam.3 is incorrect when it claims that the
pthread_attr_setschedparam function always succeeds on linux:

int main() {
   pthread_attr_t attr;
   struct sched_param p = {-1}; /* invalid priority */
   if (pthread_attr_init(&attr) == 0)
     if (pthread_attr_setschedpolicy(&attr, SCHED_OTHER) == 0)
       if (pthread_attr_setschedparam(&attr, &p) == EINVAL)
	return 1;
   return 0;
}

The program exits with exit code 1, therefore
pthread_attr_setschedparam() has returned error code EINVAL.

I could evoke this error on ubuntu 14.04, and verify it by
examining the eglibc-2.19 source code. The function is
implemented in file fbtl/pthread_attr_setschedparam.c. For
error checking, it calls the helper function
check_sched_priority_attr which is implemented inline in
file ./fbtl/pthreadP.h. This function returns EINVAL if a
range check fails.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Eric Wong 7b6a329977 sendfile.2: Caution against modifying sent pages
The following program illustrates the difference between TCP
and Unix stream sockets doing sendfile.  Since TCP implements
zero-copy, the new modifications to the file transferred is
seen upon reading despite the modifications happening after
sendfile was last called.

Unix stream sockets do not implement zero-copy (as of
Linux 3.15), so readers continue to see the contents of the
file at the time it was sent, not as they are at the time of
reading.

----------------- sendfile-mod.c ---------------
	#define _GNU_SOURCE
	#include <sys/ioctl.h>
	#include <sys/types.h>
	#include <sys/socket.h>
	#include <sys/sendfile.h>
	#include <arpa/inet.h>
	#include <stdio.h>
	#include <errno.h>
	#include <string.h>
	#include <unistd.h>
	#include <assert.h>
	#include <fcntl.h>

static void tcp_socketpair(int sv[2])
{
	struct sockaddr_in addr;
	socklen_t addrlen = sizeof(addr);
	int l = socket(PF_INET, SOCK_STREAM, 0);
	int c = socket(PF_INET, SOCK_STREAM, 0);
	int a;
	int val = 1;

	addr.sin_family = AF_INET;
	addr.sin_addr.s_addr = INADDR_ANY;
	addr.sin_port = 0;
	assert(0 == bind(l, (struct sockaddr*)&addr, addrlen));
	assert(0 == listen(l, 1024));
	assert(0 == getsockname(l, (struct sockaddr *)&addr, &addrlen));
	assert(0 == connect(c, (struct sockaddr *)&addr, addrlen));
	a = accept4(l, NULL, NULL, SOCK_NONBLOCK);
	assert(a >= 0);
	close(l);
	assert(0 == ioctl(c, FIONBIO, &val));
	sv[0] = a;
	sv[1] = c;
}

int main(int argc, char *argv[])
{
	int pair[2];
	FILE *tmp = tmpfile();
	int tfd;
	char buf[16384];
	ssize_t w, r;
	size_t i;
	const size_t n = 2048;
	off_t off = 0;
	char expect[4096];
	int flags = SOCK_STREAM|SOCK_NONBLOCK;

	tfd = fileno(tmp);
	assert(tfd >= 0);

	/* prepare the tempfile */
	memset(buf, 'a', sizeof(buf));
	for (i = 0; i < n; i++)
		assert(sizeof(buf) == write(tfd, buf, sizeof(buf)));

	if (argc == 2 && strcmp(argv[1], "unix") == 0)
		assert(0 == socketpair(AF_UNIX, flags, 0, pair));
	else if (argc == 2 && strcmp(argv[1], "pipe") == 0)
		assert(0 == pipe2(pair, O_NONBLOCK));
	else
		tcp_socketpair(pair);

	/* fill up the socket buffer */
	for (;;) {
		w = sendfile(pair[1], tfd, &off, n);
		if (w > 0)
			continue;
		if (w < 0 && errno == EAGAIN)
			break;
		assert(0 && "unhandled error" && w && errno);
	}
	printf("wrote off=%lld\n", (long long)off);

	/* rewrite the tempfile */
	memset(buf, 'A', sizeof(buf));
	assert(0 == lseek(tfd, 0, SEEK_SET));
	for (i = 0; i < n; i++)
		assert(sizeof(buf) == write(tfd, buf, sizeof(buf)));

	/* we should be reading 'a's, not 'A's */
	memset(expect, 'a', sizeof(expect));
	do {
		r = read(pair[0], buf, sizeof(expect));

		/* TCP fails here since it is zero copy (on Linux 3.15.5) */
		if (r > 0)
			assert(memcmp(buf, expect, r) == 0);
	} while (r > 0);

	return 0;
}

Signed-off-by: Eric Wong <normalperson@yhbt.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Peng Haitao 87ab04792c clone.2: Fix description of CLONE_PARENT_SETTID
CLONE_PARENT_SETTID only stores child thread ID in parent memory.

Signed-off-by: Peng Haitao <penght@cn.fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Kevin Easton 8a76b19ecd clone.2, execve.2: Document interaction of execve(2) with CLONE_FILES
This patch the fact that a successful execve(2) in a process that
is sharing a file descriptor table results in unsharing the table.

I discovered this through testing and verified it by source
inspection - there is a call to unshare_files() early in
do_execve_common().

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Jan Stancek 3d350ba3c9 migrate_pages.2: Document EFAULT and EINVAL errors
I encountered these errors while writing testcase for migrate_pages
syscall for LTP (Linux test project).

I checked stable kernel tree 3.5 to see which paths return these.
Both can be returned from get_nodes(), which is called from:
SYSCALL_DEFINE4(migrate_pages, pid_t, pid, unsigned long, maxnode,
                const unsigned long __user *, old_nodes,
                const unsigned long __user *, new_nodes)

The testcase does following:
EFAULT
a) old_nodes/new_nodes is area mmaped with PROT_NONE
b) old_nodes/new_nodes is area not mmapped in process address
   space, -1 or area that has been just munmmaped

EINVAL
a) maxnodes overflows kernel limit
b) new_nodes contain node, which has no memory or does not exist
   or is not returned for get_mempolicy(MPOL_F_MEMS_ALLOWED).

Signed-off-by: Jan Stancek <jstancek@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Rob Somers ec5308ca6e encrypt.3: Improve code example
I (and some others) found that the original example code
did not seem to work as advertised.  The new code (used by
permission of the original author, Jens Thoms Toerring)
was found on comp.os.linux.development.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:11 +01:00
Michael Kerrisk 7949b871f5 cacheflush.2: Refer reader to BUGS in discussion of EINVAL error
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:10 +01:00
Ralf Baechle 7bbc267ac3 cacheflush.2: Update some portability details and bugs
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:32:10 +01:00
Mark Seaborn b22b377bd4 mprotect.2: mention effect of READ_IMPLIES_EXEC personality flag
I puzzled over mprotect()'s effect on /proc/*/maps for a while
yesterday -- it was setting "x" without PROT_EXEC being specified.
Here is a patch to add some explanation.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 08:31:58 +01:00
Michael Kerrisk cae279c4d5 access.2: Tweaks to Denys Vlasenko's patch
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Denys Vlasenko 062d1cb332 access.2: Explain how access() check treats capabilities
We have users who are terribly confused why their binaries
with CAP_DAC_OVERRIDE capability see EACCESS from access() calls,
but are able to read the file.

The reason is access() isn't the "can I read/write/execute this
file?" question, it is the "(assuming that I'm a setuid binary,)
can *the user who invoked me* read/write/execute this file?"
question.

That's why it uses real UIDs as documented, and why it ignores
capabilities when capability-endorsed binaries are run by non-root
(this patch adds this information).

To make users more likely to notice this less-known detail,
the patch expands the explanation with rationale for this logic
into a separate paragraph.

Signed-off-by: Denys Vlasenko <dvlasenk@redhat.com>
CC: linux-man@vger.kernel.org
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Jan Chaloupka 170e5f0d95 unix.7: Mention SOCK_STREAM socket for ioctl_type of ioctl()
from https://bugzilla.redhat.com/show_bug.cgi?id=1110401.

unix.7 is not clear about socket type of ioctl_type argument of
ioctl() function. The description of SIOCINQ is applicable only
for SOCK_STREAM socket. For SOCK_DGRAM, udp(7) man page gives
correct description of SIOCINQ

Signed-off-by: Jan Chaloupka <jchaloup@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 4b081d8d9d sched_setattr.2: SYNOPSIS: remove 'const' from 'attr' sched_getattr() argument
Reported-by: Christophe Blaess <Christophe@blaess.fr>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 60569afd98 getnameinfo.3: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk c49a8e2a02 getutent.3: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 723560ba1c mlock.2: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk cd6e402be4 pciconfig_read.2: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 44da0e2405 random.4: Note maximum number of bytes returned by read(2) on /dev/random
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 866fa68185 random.4: Since Linux 3.16, reads from /dev/urandom return at most 32 MB
See https://bugs.debian.org/775328 and
https://bugzilla.kernel.org/show_bug.cgi?id=80981#c9

Reported-by: Mathieu Malaterre <malat@debian.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 792bb5ad59 random.4: Minor fixes
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michal Hocko 17ad768d41 fork.2: EAGAIN is not reported when task allocation fails
I am not sure why we have:

   "EAGAIN fork() cannot allocate sufficient memory to copy
    the parent's page tables and allocate a task structure
    or the child."

The text seems to be there from the time when man-pages
were moved to git so there is no history for it.

And it doesn't reflect reality: the kernel reports both
dup_task_struct and dup_mm failures as ENOMEM to the
userspace. This seems to be the case from early 2.x times
so let's simply remove this part.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 2702dc2175 proc.5: (Briefly) document /proc/PID/attr/socketcreate
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 666db07e1a proc.5: (Briefly) document /proc/PID/attr/keycreate
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk b7a425679b proc.5: Document /proc/PID/attr/{current,exec,fscreate,prev}
Heavily based on Stephen Smalley's text in
    https://lwn.net/Articles/28222/
    From:    Stephen Smalley <sds@epoch.ncsc.mil>
    To:      LKML and others
    Subject: [RFC][PATCH] Process Attribute API for Security Modules
    Date:    08 Apr 2003 16:17:52 -0400

Cowritten-by: Stephen Smalley <sds@tycho.nsa.gov>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk c261b0e5a5 proc.5: Document /proc/sys/kernel/auto_msgmni
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 12618ce888 intro.5: Remove words "and protocols"
There are no protocol descriptions in Section 5. Protocols are
in Section 7.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 98f792f704 semop.2: Note defaults for SEMOPM and warn against increasing > 1000
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk 8a3e6dc72f semget.2: Note default value for SEMMNI and SEMMSL
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:28 +01:00
Michael Kerrisk a75f73c22a msgget.2: Add details of MSGMNI default value
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk faeaa68cca msgop.2: Clarify wording of MSGMAX and MSGMNB limits
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 4b139190f9 signal.7: srcfix: note commit hash for futex() restart behavior change
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk f2aa4dcc8e proc.5: Note that CAP_SYS_ADMIN is required to list /proc/PID/map_files
This might however change in the future; see the Jan 2015 LKML thread:

        Re: [RFC][PATCH v2] procfs: Always expose /proc/<pid>/map_files/
                            and make it readable

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 2f2a53b56e setxattr.2: ERRORS: add ENOTSUP for invalid namespace prefix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 5e73ab4bc4 setxattr.2: Remove redundant text under ENOTSUP error
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 9398702ca2 setxattr.2: Rework text describing 'flags' argument
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 60da5b89a7 setxattr.2: Note that zero-length attribute values are permitted
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 736703bde2 setxattr.2: Minor rewordings
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 5232e869b2 setxattr.2: wfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 220b2331ef removexattr.2: wfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk 495420ae2c removexattr.2: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00
Michael Kerrisk a4526c2f11 listxattr.2: Reword discussion of size==0 case
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-02-21 07:58:27 +01:00