From b07cd0a96b33d792f08f6bdecf2ba0a3a33478b3 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 16 May 2007 05:33:35 +0000 Subject: [PATCH] Renamed RESTRICTIONS section to NOTES, or moved text in a RESTRICTIONS section under existing NOTES section. --- man2/access.2 | 3 ++- man2/chown.2 | 26 +++++++++++++------------- man2/lseek.2 | 12 ++++++------ man2/open.2 | 20 ++++++++++---------- man2/read.2 | 2 +- man5/utmp.5 | 2 +- 6 files changed, 33 insertions(+), 32 deletions(-) diff --git a/man2/access.2 b/man2/access.2 index 808cead00..7eac383e2 100644 --- a/man2/access.2 +++ b/man2/access.2 @@ -165,7 +165,7 @@ the underlying file system. Since kernel 2.6.20, .BR access () honours this flag. -.SH RESTRICTIONS +.SH NOTES .BR access () returns an error if any of the access types in the requested call fails, even if other types might be successful. @@ -175,6 +175,7 @@ may not work correctly on NFS file systems with UID mapping enabled, because UID mapping is done on the server and hidden from the client, which checks permissions. .PP +.BR Warning: Using .BR access () to check if a user is authorized to e.g. open a file before actually diff --git a/man2/chown.2 b/man2/chown.2 index a444d559a..f2db41f76 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -139,6 +139,19 @@ See above. .B EROFS See above. .SH NOTES +The +.BR chown () +semantics are deliberately violated on NFS file systems +which have UID mapping enabled. +Additionally, the semantics of all system +calls which access the file contents are violated, because +.BR chown () +may cause immediate access revocation on already open files. +Client side +caching may lead to a delay between the time where ownership have +been changed to allow access for a user and the time where the file can +actually be accessed by the user on other clients. + In versions of Linux prior to 2.1.81 (and distinct from 2.1.46), .BR chown () did not follow symbolic links. @@ -170,19 +183,6 @@ used by the superuser (that is, ordinary users cannot give away files). .\" fchown(): .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK .\" error conditions. -.SH RESTRICTIONS -The -.BR chown () -semantics are deliberately violated on NFS file systems -which have UID mapping enabled. -Additionally, the semantics of all system -calls which access the file contents are violated, because -.BR chown () -may cause immediate access revocation on already open files. -Client side -caching may lead to a delay between the time where ownership have -been changed to allow access for a user and the time where the file can -actually be accessed by the user on other clients. .SH "SEE ALSO" .BR chmod (2), .BR fchownat (2), diff --git a/man2/lseek.2 b/man2/lseek.2 index 1180fe013..f2beef0d2 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -115,21 +115,21 @@ The resulting file offset cannot be represented in an is associated with a pipe, socket, or FIFO. .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001. -.SH RESTRICTIONS +.SH NOTES +This document's use of +.I whence +is incorrect English, but maintained for historical reasons. + Some devices are incapable of seeking and POSIX does not specify which devices must support .BR lseek (). -Linux specific restrictions: using +On Linux, using .BR lseek () on a tty device returns \fBESPIPE\fP. .\" Other systems return the number of written characters, .\" using SEEK_SET to set the counter. (Of written characters.) -.SH NOTES -This document's use of -.I whence -is incorrect English, but maintained for historical reasons. When converting old code, substitute values for \fIwhence\fP with the following macros: diff --git a/man2/open.2 b/man2/open.2 index b9e6a26c1..2b6efd4f2 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -281,7 +281,7 @@ Any .BR write (2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware. -.IR "But see RESTRICTIONS below" . +.IR "But see NOTES below" . .TP .B O_TRUNC If the file already exists and is a regular file and the open mode allows @@ -370,6 +370,15 @@ return the new file descriptor, or \-1 if an error occurred .I errno is set appropriately). .SH NOTES +There are many infelicities in the protocol underlying NFS, affecting +amongst others +.BR O_SYNC " and " O_NDELAY . + +POSIX provides for three different variants of synchronised I/O, +corresponding to the flags \fBO_SYNC\fR, \fBO_DSYNC\fR and +\fBO_RSYNC\fR. +Currently (2.1.130) these are all synonymous under Linux. + Note that .BR open () can open device special files, but @@ -571,15 +580,6 @@ use to enable this flag. .\" FIXME Check bugzilla report on open(O_ASYNC) .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 -.SH RESTRICTIONS -There are many infelicities in the protocol underlying NFS, affecting -amongst others -.BR O_SYNC " and " O_NDELAY . - -POSIX provides for three different variants of synchronised I/O, -corresponding to the flags \fBO_SYNC\fR, \fBO_DSYNC\fR and -\fBO_RSYNC\fR. -Currently (2.1.130) these are all synonymous under Linux. .SH "SEE ALSO" .BR close (2), .BR dup (2), diff --git a/man2/read.2 b/man2/read.2 index f77113dcb..598eaffcb 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -124,7 +124,7 @@ to return \-1 (with set to EINTR) or to return the number of bytes already read. .SH "CONFORMING TO" SVr4, 4.3BSD, POSIX.1-2001. -.SH RESTRICTIONS +.SH NOTES On NFS file systems, reading small amounts of data will only update the time stamp the first time, subsequent calls may not do so. This is caused diff --git a/man5/utmp.5 b/man5/utmp.5 index 1b9f0767b..5e2cbb591 100644 --- a/man5/utmp.5 +++ b/man5/utmp.5 @@ -273,7 +273,7 @@ binaries using the old libc5 struct will corrupt Debian systems include a patched libc5 which uses the new utmp format. The problem still exists with wtmp since it's accessed directly in libc5. -.SH RESTRICTIONS +.SH NOTES The file format is machine dependent, so it is recommended that it be processed only on the machine architecture where it was created. .PP