LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

Reordered sections for consistency.

This commit is contained in:
Michael Kerrisk 2007-05-18 16:30:46 +00:00
parent a1d5f77cc8
commit 2dd578fd5b
30 changed files with 138 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Changes
View File

@ -14,6 +14,9 @@ Global changes
--------------
Reordered sections to be more consistent, in some cases renaming
sections or shifting paragraphs between sections.
Changes to individual pages
---------------------------

4
man2/seteuid.2
View File

@ -71,6 +71,8 @@ and
.IR egid )
is not the real user (group) ID, the effective user (group) ID,
or the saved set-user-ID (saved set-group-ID).
.SH "CONFORMING TO"
4.3BSD, POSIX.1-2001.
.SH NOTES
Setting the effective user (group) ID to the
saved set-user-ID (saved set-group-ID) is
@ -87,8 +89,6 @@ Under glibc2.1 it is equivalent to
and hence does not change the saved set-user-ID.
Similar remarks hold for
.BR setegid ().
.SH "CONFORMING TO"
4.3BSD, POSIX.1-2001.
.SH "SEE ALSO"
.BR geteuid (2),
.BR setresuid (2),

16
man2/setfsuid.2
View File

@ -75,14 +75,6 @@ is returned.
is Linux specific and should not be used in programs intended
to be portable.
It is present since Linux 1.1.44 and in libc since libc 4.7.6.
.SH BUGS
No error messages of any kind are returned to the caller.
At the very
least,
.B EPERM
should be returned when the call fails (because the caller lacks the
.B CAP_SETUID
capability).
.SH NOTES
When glibc determines that the argument is not a valid user ID,
it will return \-1 and set \fIerrno\fP to EINVAL without attempting
@ -91,6 +83,14 @@ the system call.
Note that at the time this system call was introduced, a process
could send a signal to a process with the same effective user ID.
Today signal permission handling is slightly different.
.SH BUGS
No error messages of any kind are returned to the caller.
At the very
least,
.B EPERM
should be returned when the call fails (because the caller lacks the
.B CAP_SETUID
capability).
.SH "SEE ALSO"
.BR kill (2),
.BR setfsgid (2),

8
man2/shutdown.2
View File

@ -81,15 +81,15 @@ The specified socket is not connected.
.B ENOTSOCK
.I s
is a file, not a socket.
.SH "CONFORMING TO"
POSIX.1-2001, 4.4BSD (the
.BR shutdown ()
function call first appeared in 4.2BSD).
.SH NOTES
The constants SHUT_RD, SHUT_WR, SHUT_RDWR have the value 0, 1, 2,
respectively, and are defined in
.I <sys/socket.h>
since glibc-2.1.91.
.SH "CONFORMING TO"
POSIX.1-2001, 4.4BSD (the
.BR shutdown ()
function call first appeared in 4.2BSD).
.SH "SEE ALSO"
.BR connect (2),
.BR socket (2)

6
man2/sigaction.2
View File

@ -383,6 +383,9 @@ This will also be generated if an attempt
is made to change the action for
.BR SIGKILL " or " SIGSTOP ", "
which cannot be caught or ignored.
.SH "CONFORMING TO"
POSIX.1-2001, SVr4.
.\" SVr4 does not document the EINTR condition.
.SH NOTES
.PP
According to POSIX, the behaviour of a process is undefined after it
@ -494,9 +497,6 @@ preventing not only the delivered signal from being masked during
execution of the handler, but also the signals specified in
.IR sa_mask .
This bug is was fixed in kernel 2.6.14.
.SH "CONFORMING TO"
POSIX.1-2001, SVr4.
.\" SVr4 does not document the EINTR condition.
.SH "SEE ALSO"
.BR kill (1),
.BR kill (2),

4
man2/sigaltstack.2
View File

@ -147,6 +147,8 @@ if (sigaltstack(&ss, NULL) == \-1)
/* Handle error */;
.fi
.RE
.SH "CONFORMING TO"
SUSv2, SVr4, POSIX.1-2001.
.SH NOTES
The most common usage of an alternate signal stack is to handle the
.B SIGSEGV
@ -201,8 +203,6 @@ system call.
It used a slightly
different struct, and had the major disadvantage that the caller
had to know the direction of stack growth.
.SH "CONFORMING TO"
SUSv2, SVr4, POSIX.1-2001.
.SH "SEE ALSO"
.BR execve (2),
.BR setrlimit (2),

4
man2/signal.2
View File

@ -79,6 +79,8 @@ The
function returns the previous value of the signal handler, or
.B SIG_ERR
on error.
.SH "CONFORMING TO"
C89, C99, POSIX.1-2001.
.SH NOTES
The effects of this call in a multi-threaded process are unspecified.
.PP
@ -159,8 +161,6 @@ It is better to avoid
altogether, and use
.BR sigaction (2)
instead.
.SH "CONFORMING TO"
C89, C99, POSIX.1-2001.
.SH "SEE ALSO"
.BR kill (1),
.BR alarm (2),

4
man2/sigpending.2
View File

@ -46,12 +46,12 @@ returns 0 on success and \-1 on error.
.B EFAULT
.IR set
points to memory which is not a valid part of the process address space.
.SH "CONFORMING TO"
POSIX.1-2001.
.SH NOTES
See
.BR sigsetops (3)
for details on manipulating signal sets.
.SH "CONFORMING TO"
POSIX.1-2001.
.SH BUGS
In versions of glibc up to and including 2.2.1,
there is a bug in the wrapper function for

4
man2/sigprocmask.2
View File

@ -82,6 +82,8 @@ returns 0 on success and \-1 on error.
The value specified in
.I how
was invalid.
.SH "CONFORMING TO"
POSIX.1-2001.
.SH NOTES
It is not possible to block
.BR SIGKILL " or " SIGSTOP .
@ -104,8 +106,6 @@ or
See
.BR sigsetops (3)
for details on manipulating signal sets.
.SH "CONFORMING TO"
POSIX.1-2001.
.SH "SEE ALSO"
.BR kill (2),
.BR pause (2),

4
man2/sigqueue.2
View File

@ -96,6 +96,8 @@ For the required permissions, see
.B ESRCH
No process has a PID matching
.IR pid .
.SH "CONFORMING TO"
POSIX.1-2001
.SH NOTES
If this function results in the sending of a signal to the process
that invoked it, and that signal was not blocked by the calling thread,
@ -104,8 +106,6 @@ having it unblocked, or by waiting for it using
.BR sigwait (3)),
then at least some signal must be delivered to this thread before this
function returns.
.SH "CONFORMING TO"
POSIX.1-2001
.SH "SEE ALSO"
.BR kill (2),
.BR sigaction (2),

8
man2/sigreturn.2
View File

@ -43,6 +43,10 @@ interrupted by the signal.
.SH "RETURN VALUE"
.BR sigreturn ()
never returns.
.SH "CONFORMING TO"
.BR sigreturn ()
is specific to Linux and should not be used in programs intended to be
portable.
.SH NOTES
The
.BR sigreturn ()
@ -53,10 +57,6 @@ be called directly.
Better yet, the specific use of the
.I __unused
argument varies depending on the architecture.
.SH "CONFORMING TO"
.BR sigreturn ()
is specific to Linux and should not be used in programs intended to be
portable.
.SH FILES
/usr/src/linux/arch/i386/kernel/signal.c
.br

4
man2/sigsuspend.2
View File

@ -64,6 +64,8 @@ points to memory which is not a valid part of the process address space.
.TP
.B EINTR
The call was interrupted by a signal.
.SH "CONFORMING TO"
POSIX.1-2001.
.SH NOTES
.PP
Normally,
@ -86,8 +88,6 @@ argument).
See
.BR sigsetops (3)
for details on manipulating signal sets.
.SH "CONFORMING TO"
POSIX.1-2001.
.SH "SEE ALSO"
.BR kill (2),
.BR pause (2),

4
man2/sigwaitinfo.2
View File

@ -110,6 +110,8 @@ The wait was interrupted by a signal handler.
.B EINVAL
.I timeout
was invalid.
.SH "CONFORMING TO"
POSIX.1-2001
.SH NOTES
In normal usage, the calling program blocks the signals in
.I set
@ -136,8 +138,6 @@ unspecified, permitting the possibility that this has the same meaning
as a call to
.BR sigwaitinfo (),
and indeed this is what is done on Linux.
.SH "CONFORMING TO"
POSIX.1-2001
.SH "SEE ALSO"
.BR kill (2),
.BR sigaction (2),

4
man2/splice.2
View File

@ -156,6 +156,8 @@ was not NULL, but the corresponding file descriptor refers to a pipe.
The
.BR splice (2)
system call first appeared in Linux-2.6.17.
.SH "CONFORMING TO"
This system call is Linux specific.
.SH NOTES
The three system calls
.BR splice (2),
@ -210,8 +212,6 @@ only pointers are copied, not the pages of the buffer.
.SH EXAMPLE
See
.BR tee (2).
.SH "CONFORMING TO"
This system call is Linux specific.
.SH SEE ALSO
.BR sendfile (2),
.BR splice (2),

12
man2/symlink.2
View File

@ -128,6 +128,12 @@ does not support the creation of symbolic links.
.B EROFS
.I newpath
is on a read-only filesystem.
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.\" SVr4 documents additional error codes EDQUOT and ENOSYS.
.\" See
.\" .BR open (2)
.\" re multiple files with the same name, and NFS.
.SH NOTES
No checking of
.I oldpath
@ -137,12 +143,6 @@ Deleting the name referred to by a symlink will actually delete the
file (unless it also has other hard links).
If this behaviour is not desired, use
.BR link (2).
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.\" SVr4 documents additional error codes EDQUOT and ENOSYS.
.\" See
.\" .BR open (2)
.\" re multiple files with the same name, and NFS.
.SH "SEE ALSO"
.BR ln (1),
.BR link (2),

12
man2/symlinkat.2
View File

@ -92,17 +92,17 @@ is not a valid file descriptor.
is relative and
.I newdirfd
is a file descriptor referring to a file other than a directory.
.SH VERSIONS
.BR symlinkat ()
was added to Linux in kernel 2.6.16.
.SH "CONFORMING TO"
This system call is non-standard but is proposed
for inclusion in a future revision of POSIX.1.
.SH NOTES
See
.BR openat (2)
for an explanation of the need for
.BR symlinkat ().
.SH "CONFORMING TO"
This system call is non-standard but is proposed
for inclusion in a future revision of POSIX.1.
.SH VERSIONS
.BR symlinkat ()
was added to Linux in kernel 2.6.16.
.SH "SEE ALSO"
.BR openat (2),
.BR path_resolution (2),

14
man2/sync.2
View File

@ -45,6 +45,13 @@ first commits inodes to buffers, and then buffers to disk.
This function is always successful.
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.SH NOTES
Since glibc 2.2.2 the Linux prototype is as listed above,
following the various standards.
In libc4, libc5, and glibc up to 2.2.1
it was "int sync(void)", and
.BR sync ()
always returned 0.
.SH BUGS
According to the standard specification (e.g., POSIX.1-2001),
.BR sync ()
@ -53,13 +60,6 @@ writing is done.
However, since version 1.3.20 Linux does actually wait.
(This still does not guarantee data integrity: modern disks have
large caches.)
.SH NOTES
Since glibc 2.2.2 the Linux prototype is as listed above,
following the various standards.
In libc4, libc5, and glibc up to 2.2.1
it was "int sync(void)", and
.BR sync ()
always returned 0.
.SH "SEE ALSO"
.BR bdflush (2),
.BR fdatasync (2),

6
man2/sync_file_range.2
View File

@ -156,12 +156,12 @@ a directory, or a symbolic link.
.\" FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)?
.\" (In userspace at least) it isn't possible to obtain a file descriptor
.\" for a symbolic link.
.SH "CONFORMING TO"
This system call is Linux specific, and should be avoided
in portable programs.
.SH VERSIONS
.BR sync_file_range ()
appeared on Linux in kernel 2.6.17.
.SH "CONFORMING TO"
This system call is Linux specific, and should be avoided
in portable programs.
.SH "SEE ALSO"
.BR fdatasync (2),
.BR fsync (2),

12
man2/tee.2
View File

@ -110,6 +110,12 @@ refer to the same pipe.
.TP
.B ENOMEM
Out of memory.
.SH VERSIONS
The
.BR tee (2)
system call first appeared in Linux-2.6.17.
.SH "CONFORMING TO"
This system call is Linux specific.
.SH NOTES
Conceptually,
.BR tee ()
@ -184,12 +190,6 @@ main(int argc, char *argv[])
exit(EXIT_SUCCESS);
}
.fi
.SH VERSIONS
The
.BR tee (2)
system call first appeared in Linux-2.6.17.
.SH "CONFORMING TO"
This system call is Linux specific.
.SH SEE ALSO
.BR splice (2),
.BR vmsplice (2),

12
man2/time.2
View File

@ -52,6 +52,12 @@ appropriately.
.B EFAULT
.I t
points outside your accessible address space.
.SH "CONFORMING TO"
SVr4, 4.3BSD, C89, C99, POSIX.1-2001.
.\" .br
.\" Under 4.3BSD, this call is obsoleted by
.\" .BR gettimeofday (2).
POSIX does not specify any error conditions.
.SH NOTES
POSIX.1 defines
.I seconds since the Epoch
@ -65,12 +71,6 @@ required to be synchronised to a standard reference.
The intention is
that the interpretation of seconds since the Epoch values be
consistent; see POSIX.1 Annex B 2.2.2 for further rationale.
.SH "CONFORMING TO"
SVr4, 4.3BSD, C89, C99, POSIX.1-2001.
.\" .br
.\" Under 4.3BSD, this call is obsoleted by
.\" .BR gettimeofday (2).
POSIX does not specify any error conditions.
.SH "SEE ALSO"
.BR date (1),
.BR gettimeofday (2),

4
man2/times.2
View File

@ -110,6 +110,8 @@ The return value may overflow the possible range of type
On error, \fI(clock_t) \-1\fP is returned, and
.I errno
is set appropriately.
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.SH NOTES
The number of clock ticks per second can be obtained using
.RS
@ -169,8 +171,6 @@ V7 used
for the struct members, because it had no type
.I time_t
yet.
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.SH "SEE ALSO"
.BR time (1),
.BR getrusage (2),

10
man2/tkill.2
View File

@ -90,17 +90,17 @@ For the required permissions, see
.TP
.B ESRCH
No process with the specified thread ID (and thread group ID) exists.
.SH VERSIONS
.BR tkill ()
is supported since Linux 2.4.19 / 2.5.4.
.BR tgkill ()
was added in Linux 2.5.75.
.SH "CONFORMING TO"
.BR tkill ()
and
.BR tgkill ()
are Linux specific and should not be used
in programs that are intended to be portable.
.SH VERSIONS
.BR tkill ()
is supported since Linux 2.4.19 / 2.5.4.
.BR tgkill ()
was added in Linux 2.5.75.
.SH "SEE ALSO"
.BR gettid (2),
.BR kill (2)

4
man2/umask.2
View File

@ -86,14 +86,14 @@ resulting file will be:
.SH "RETURN VALUE"
This system call always succeeds and the previous value of the mask
is returned.
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.SH NOTES
A child process created via
.BR fork (2)
inherits its parent's umask.
The umask is left unchanged by
.BR execve (2).
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.SH "SEE ALSO"
.BR chmod (2),
.BR mkdir (2),

14
man2/unlinkat.2
View File

@ -129,18 +129,18 @@ An invalid flag value was specified in
is relative and
.I dirfd
is a file descriptor referring to a file other than a directory.
.SH VERSIONS
.BR unlinkat ()
was added to Linux in kernel 2.6.16.
.SH "CONFORMING TO"
This system call is non-standard but is proposed
for inclusion in a future revision of POSIX.1.
A similar system call exists on Solaris.
.SH NOTES
See
.BR openat (2)
for an explanation of the need for
.BR unlinkat ().
.SH "CONFORMING TO"
This system call is non-standard but is proposed
for inclusion in a future revision of POSIX.1.
A similar system call exists on Solaris.
.SH VERSIONS
.BR unlinkat ()
was added to Linux in kernel 2.6.16.
.SH "SEE ALSO"
.BR openat (2),
.BR path_resolution (2),

8
man2/unshare.2
View File

@ -136,14 +136,14 @@ context that need to be unshared.
.B EINVAL
An invalid bit was specified in
.IR flags .
.SH CONFORMING TO
The
.BR unshare ()
system call is Linux specific.
.SH VERSIONS
The
.BR unshare ()
system call was added to Linux in kernel 2.6.16.
.SH CONFORMING TO
The
.BR unshare ()
system call is Linux specific.
.SH NOTES
Not all of the process attributes that can be shared when
a new process is created using

16
man2/utime.2
View File

@ -132,6 +132,14 @@ is not NULL and the process does not have permission to change the time stamps.
.B EROFS
.I path
resides on a read-only file system.
.SH "CONFORMING TO"
.BR utime ():
SVr4, POSIX.1-2001.
.\" SVr4 documents additional error conditions EFAULT,
.\" EINTR, ELOOP, EMULTIHOP, ENAMETOOLONG, ENOLINK, ENOLINK, ENOTDIR.
.br
.BR utimes ():
4.3BSD
.SH NOTES
Linux does not allow changing the time stamps on an immutable file,
or setting the time stamps to something other than the current time
@ -151,14 +159,6 @@ legacy, which is strange since it provides more functionality than
Linux is not careful to distinguish between the EACCES and EPERM error returns.
On the other hand, POSIX.1-2001 is buggy in its error description for
.BR utimes ().
.SH "CONFORMING TO"
.BR utime ():
SVr4, POSIX.1-2001.
.\" SVr4 documents additional error conditions EFAULT,
.\" EINTR, ELOOP, EMULTIHOP, ENAMETOOLONG, ENOLINK, ENOLINK, ENOTDIR.
.br
.BR utimes ():
4.3BSD
.SH "SEE ALSO"
.BR chattr (1),
.BR futimesat (2),

52
man2/vfork.2
View File

@ -114,32 +114,6 @@ The use of
was tricky: for example, not modifying data
in the parent process depended on knowing which variables are
held in a register.
.SH BUGS
It is rather unfortunate that Linux revived this spectre from the past.
The BSD manpage states:
"This system call will be eliminated when proper system sharing mechanisms
are implemented.
Users should not depend on the memory sharing semantics of
.BR vfork ()
as it will, in that case, be made synonymous to
.BR fork (2).\c
"
Details of the signal handling are obscure and differ between systems.
The BSD manpage states:
"To avoid a possible deadlock situation, processes that are children
in the middle of a
.BR vfork ()
are never sent SIGTTOU or SIGTTIN signals; rather, output or
.IR ioctl s
are allowed and input attempts result in an end-of-file indication."
.\"
.\" As far as I can tell, the following is not true in 2.6.19:
.\" Currently (Linux 2.3.25),
.\" .BR strace (1)
.\" cannot follow
.\" .BR vfork ()
.\" and requires a kernel patch.
.SH "CONFORMING TO"
4.3BSD, POSIX.1-2001.
.\" FIXME Mar 07: in the draft of the next POSIX revision, the spec for
@ -184,6 +158,32 @@ until 2.2.0-pre6 or so.
Since 2.2.0-pre9 (on i386, somewhat later on
other architectures) it is an independent system call.
Support was added in glibc 2.0.112.
.SH BUGS
It is rather unfortunate that Linux revived this spectre from the past.
The BSD manpage states:
"This system call will be eliminated when proper system sharing mechanisms
are implemented.
Users should not depend on the memory sharing semantics of
.BR vfork ()
as it will, in that case, be made synonymous to
.BR fork (2).\c
"
Details of the signal handling are obscure and differ between systems.
The BSD manpage states:
"To avoid a possible deadlock situation, processes that are children
in the middle of a
.BR vfork ()
are never sent SIGTTOU or SIGTTIN signals; rather, output or
.IR ioctl s
are allowed and input attempts result in an end-of-file indication."
.\"
.\" As far as I can tell, the following is not true in 2.6.19:
.\" Currently (Linux 2.3.25),
.\" .BR strace (1)
.\" cannot follow
.\" .BR vfork ()
.\" and requires a kernel patch.
.SH "SEE ALSO"
.BR clone (2),
.BR execve (2),

12
man2/vmsplice.2
View File

@ -134,6 +134,12 @@ set.
.TP
.B ENOMEM
Out of memory.
.SH VERSIONS
The
.BR vmsplice (2)
system call first appeared in Linux-2.6.17.
.SH "CONFORMING TO"
This system call is Linux specific.
.SH NOTES
.BR vmsplice ()
follows the other vectorized read/write type functions when it comes to
@ -143,12 +149,6 @@ This limit is
as defined in
.IR <limits.h> .
At the time of this writing, that limit is 1024.
.SH VERSIONS
The
.BR vmsplice (2)
system call first appeared in Linux-2.6.17.
.SH "CONFORMING TO"
This system call is Linux specific.
.SH SEE ALSO
.BR splice (2),
.BR tee (2),

4
man2/wait.2
View File

@ -396,6 +396,8 @@ was caught.
The
.I options
argument was invalid.
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.SH NOTES
A child that terminates, but has not been waited for becomes a "zombie".
The kernel maintains a minimal set of information about the zombie
@ -562,8 +564,6 @@ main(int argc, char *argv[])
}
}
.fi
.SH "CONFORMING TO"
SVr4, 4.3BSD, POSIX.1-2001.
.SH "SEE ALSO"
.BR _exit (2),
.BR clone (2),

4
man2/wait4.2
View File

@ -114,6 +114,8 @@ As for
.SH ERRORS
As for
.BR waitpid (2).
.SH "CONFORMING TO"
4.3BSD
.SH NOTES
Including
.I <sys/time.h>
@ -126,8 +128,6 @@ structure with fields of type
.I struct timeval
defined in
.IR <sys/time.h> .)
.SH "CONFORMING TO"
4.3BSD
.SH "SEE ALSO"
.BR fork (2),
.BR getrusage (2),