Re: svn commit: r255486 - in head/lib/libc: gen sys
On 9/12/2013 8:15 AM, Bruce Evans wrote: On Thu, 12 Sep 2013, Bryan Drewery wrote: On 9/12/2013 6:36 AM, Hiroki Sato wrote: Bryan Drewery bdrew...@freebsd.org wrote in 201309120053.r8c0rc7h082...@svn.freebsd.org: bd Author: bdrewery (ports committer) bd Date: Thu Sep 12 00:53:38 2013 bd New Revision: 255486 bd URL: http://svnweb.freebsd.org/changeset/base/255486 bd bd Log: bd Consistently reference file descriptors as fd. 55 other manpages Inconsistently... bd used fd, while these used d and filedes. ... About 57 man pages (counting links multiply) in /usr/share/man[23] still use the POSIX spelling fildes. Yes I see I did miss a few. POSIX never uses the spelling filedes, at least in the old 2001 draft7.txt. But it is inconsistent between fildes and fd. In the old draft, it uses int fildes on 67 lines (including for most of the functions changed in this commit). It uses int fd on 40 lines. But most of the latter are not for prototypes. The only exceptions are for posix_fadvise() and posix_fallocate(). Anyway, this change mainly improves d to fd. filedes - fd is not so clearly an improvement, but filedes was only used in a couple of files and thus rarely changed. I think chroot.2 still has the grammar error filedescriptors in descriptions. Normal English grammar file descriptors is used in about 872 man pages (counting links multiply) in /usr/share/man[23]. I am mostly interested at the moment in updating the variable names, and not the descriptions. bd bd MFC after:1 week bd Approved by:gjb bd Approved by:re (delphij) I think this kind of changes need a consensus because several POSIX functions use filedes in the specification document. r254484 by pjd was a similar change (s/type/af/ in gethostbyaddr()). In SUSv4, fdopen() uses filedes and openat() uses fd, for example. Consistency throughout our manual pages is generally good. However, I also see the benefit of using the same expression as the specification even if it is inconsistent. What do you think? Does it really use filedes? POSIX still never uses this in the 2007 draft (austin-d2r.pdf). It uses fildes for fdopen(), but fd for fdopendir() and openat(). It still uses fd for posix_fadvise() and posix_fallocate(). I now think that the fds in POSIX are just style bugs. The normal fildes had only rotted to fd in 2 places in 2001, but rotted much further in 2007. If we ever copied the POSIX spec to improve FreeBSD man pages, then it would be painful to make any changes to the text (other than deshallify, and I wouldn't trust that either). FreeBSD now copies the POSIX inconsistencies for fildes vs fd for at least fdopen() and fdopendir(), although it doesn't copy whole sections of POSIX for these functions (or any at all?). I did notice that 'filedes' was referenced in some specs, but it's very weird to open multiple manpages and expect 'fd' and find 'd' and rework my brain to understand that 'd' or 'filedes' is just a 'fd'. Takes a second of thinking. It was surprising to me when I noticed it, especially given how many used 'fd'. fd is a good abbreviation, but fildes is more formal. I actually prefer fd throughout. fildes is not such a good abbreviation, since it is half-way. Using both is just a style bug that is not quite as confusing as using d and fd. Using d, fd, fildes and filedes was a larger style bug. Bruce Should I revert until we can have more discussion on this and what impact it has on maintaining the manpages? -- Regards, Bryan Drewery signature.asc Description: OpenPGP digital signature
Re: svn commit: r255486 - in head/lib/libc: gen sys
Bruce Evans b...@optusnet.com.au wrote in 2013091312.k1...@besplex.bde.org: br On 9/12/2013 6:36 AM, Hiroki Sato wrote: br I think this kind of changes need a consensus because several POSIX br functions use filedes in the specification document. r254484 by br pjd was a similar change (s/type/af/ in gethostbyaddr()). br br In SUSv4, fdopen() uses filedes and openat() uses fd, for br example. Consistency throughout our manual pages is generally good. br However, I also see the benefit of using the same expression as the br specification even if it is inconsistent. What do you think? br br Does it really use filedes? POSIX still never uses this in the 2007 br draft (austin-d2r.pdf). It uses fildes for fdopen(), but fd for br fdopendir() and openat(). It still uses fd for posix_fadvise() and br posix_fallocate(). I now think that the fds in POSIX are just br style bugs. The normal fildes had only rotted to fd in 2 places br in 2001, but rotted much further in 2007. No, it was fildes, not filedes, as you pointed out. It seems that my fingers preferred e over d after fil... -- Hiroki pgp1azXFfBcMI.pgp Description: PGP signature
Re: svn commit: r255486 - in head/lib/libc: gen sys
Bryan Drewery bdrew...@freebsd.org wrote in 201309120053.r8c0rc7h082...@svn.freebsd.org: bd Author: bdrewery (ports committer) bd Date: Thu Sep 12 00:53:38 2013 bd New Revision: 255486 bd URL: http://svnweb.freebsd.org/changeset/base/255486 bd bd Log: bd Consistently reference file descriptors as fd. 55 other manpages bd used fd, while these used d and filedes. bd bd MFC after:1 week bd Approved by: gjb bd Approved by: re (delphij) I think this kind of changes need a consensus because several POSIX functions use filedes in the specification document. r254484 by pjd was a similar change (s/type/af/ in gethostbyaddr()). In SUSv4, fdopen() uses filedes and openat() uses fd, for example. Consistency throughout our manual pages is generally good. However, I also see the benefit of using the same expression as the specification even if it is inconsistent. What do you think? -- Hiroki pgphZ4Nb6H6dY.pgp Description: PGP signature
Re: svn commit: r255486 - in head/lib/libc: gen sys
On 9/12/2013 6:36 AM, Hiroki Sato wrote: Bryan Drewery bdrew...@freebsd.org wrote in 201309120053.r8c0rc7h082...@svn.freebsd.org: bd Author: bdrewery (ports committer) bd Date: Thu Sep 12 00:53:38 2013 bd New Revision: 255486 bd URL: http://svnweb.freebsd.org/changeset/base/255486 bd bd Log: bd Consistently reference file descriptors as fd. 55 other manpages bd used fd, while these used d and filedes. bd bd MFC after: 1 week bd Approved by:gjb bd Approved by:re (delphij) I think this kind of changes need a consensus because several POSIX functions use filedes in the specification document. r254484 by pjd was a similar change (s/type/af/ in gethostbyaddr()). In SUSv4, fdopen() uses filedes and openat() uses fd, for example. Consistency throughout our manual pages is generally good. However, I also see the benefit of using the same expression as the specification even if it is inconsistent. What do you think? -- Hiroki I did notice that 'filedes' was referenced in some specs, but it's very weird to open multiple manpages and expect 'fd' and find 'd' and rework my brain to understand that 'd' or 'filedes' is just a 'fd'. Takes a second of thinking. It was surprising to me when I noticed it, especially given how many used 'fd'. -- Regards, Bryan Drewery signature.asc Description: OpenPGP digital signature
Re: svn commit: r255486 - in head/lib/libc: gen sys
On Thu, 12 Sep 2013, Bryan Drewery wrote: On 9/12/2013 6:36 AM, Hiroki Sato wrote: Bryan Drewery bdrew...@freebsd.org wrote in 201309120053.r8c0rc7h082...@svn.freebsd.org: bd Author: bdrewery (ports committer) bd Date: Thu Sep 12 00:53:38 2013 bd New Revision: 255486 bd URL: http://svnweb.freebsd.org/changeset/base/255486 bd bd Log: bd Consistently reference file descriptors as fd. 55 other manpages Inconsistently... bd used fd, while these used d and filedes. ... About 57 man pages (counting links multiply) in /usr/share/man[23] still use the POSIX spelling fildes. POSIX never uses the spelling filedes, at least in the old 2001 draft7.txt. But it is inconsistent between fildes and fd. In the old draft, it uses int fildes on 67 lines (including for most of the functions changed in this commit). It uses int fd on 40 lines. But most of the latter are not for prototypes. The only exceptions are for posix_fadvise() and posix_fallocate(). Anyway, this change mainly improves d to fd. filedes - fd is not so clearly an improvement, but filedes was only used in a couple of files and thus rarely changed. I think chroot.2 still has the grammar error filedescriptors in descriptions. Normal English grammar file descriptors is used in about 872 man pages (counting links multiply) in /usr/share/man[23]. bd bd MFC after: 1 week bd Approved by: gjb bd Approved by: re (delphij) I think this kind of changes need a consensus because several POSIX functions use filedes in the specification document. r254484 by pjd was a similar change (s/type/af/ in gethostbyaddr()). In SUSv4, fdopen() uses filedes and openat() uses fd, for example. Consistency throughout our manual pages is generally good. However, I also see the benefit of using the same expression as the specification even if it is inconsistent. What do you think? Does it really use filedes? POSIX still never uses this in the 2007 draft (austin-d2r.pdf). It uses fildes for fdopen(), but fd for fdopendir() and openat(). It still uses fd for posix_fadvise() and posix_fallocate(). I now think that the fds in POSIX are just style bugs. The normal fildes had only rotted to fd in 2 places in 2001, but rotted much further in 2007. If we ever copied the POSIX spec to improve FreeBSD man pages, then it would be painful to make any changes to the text (other than deshallify, and I wouldn't trust that either). FreeBSD now copies the POSIX inconsistencies for fildes vs fd for at least fdopen() and fdopendir(), although it doesn't copy whole sections of POSIX for these functions (or any at all?). I did notice that 'filedes' was referenced in some specs, but it's very weird to open multiple manpages and expect 'fd' and find 'd' and rework my brain to understand that 'd' or 'filedes' is just a 'fd'. Takes a second of thinking. It was surprising to me when I noticed it, especially given how many used 'fd'. fd is a good abbreviation, but fildes is more formal. I actually prefer fd throughout. fildes is not such a good abbreviation, since it is half-way. Using both is just a style bug that is not quite as confusing as using d and fd. Using d, fd, fildes and filedes was a larger style bug. Bruce ___ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to svn-src-all-unsubscr...@freebsd.org
svn commit: r255486 - in head/lib/libc: gen sys
Author: bdrewery (ports committer) Date: Thu Sep 12 00:53:38 2013 New Revision: 255486 URL: http://svnweb.freebsd.org/changeset/base/255486 Log: Consistently reference file descriptors as fd. 55 other manpages used fd, while these used d and filedes. MFC after:1 week Approved by: gjb Approved by: re (delphij) Modified: head/lib/libc/gen/lockf.3 head/lib/libc/sys/close.2 head/lib/libc/sys/ioctl.2 head/lib/libc/sys/read.2 head/lib/libc/sys/socketpair.2 head/lib/libc/sys/write.2 Modified: head/lib/libc/gen/lockf.3 == --- head/lib/libc/gen/lockf.3 Thu Sep 12 00:46:32 2013(r255485) +++ head/lib/libc/gen/lockf.3 Thu Sep 12 00:53:38 2013(r255486) @@ -29,7 +29,7 @@ .\ .\ $FreeBSD$ .\ -.Dd December 19, 1997 +.Dd September 11, 2013 .Dt LOCKF 3 .Os .Sh NAME @@ -40,7 +40,7 @@ .Sh SYNOPSIS .In unistd.h .Ft int -.Fn lockf int filedes int function off_t size +.Fn lockf int fd int function off_t size .Sh DESCRIPTION The .Fn lockf @@ -52,7 +52,7 @@ either return an error value or block un All the locks for a process are removed when the process terminates. .Pp The argument -.Fa filedes +.Fa fd is an open file descriptor. The file descriptor must have been opened either for write-only .Dv ( O_WRONLY ) @@ -207,7 +207,7 @@ or and the section is already locked by another process. .It Bq Er EBADF The argument -.Fa filedes +.Fa fd is not a valid open file descriptor. .Pp The argument @@ -217,7 +217,7 @@ is or .Dv F_TLOCK , and -.Fa filedes +.Fa fd is not a valid file descriptor open for writing. .It Bq Er EDEADLK The argument @@ -243,7 +243,7 @@ or .Dv F_TEST . .Pp The argument -.Fa filedes +.Fa fd refers to a file that does not support locking. .It Bq Er ENOLCK The argument Modified: head/lib/libc/sys/close.2 == --- head/lib/libc/sys/close.2 Thu Sep 12 00:46:32 2013(r255485) +++ head/lib/libc/sys/close.2 Thu Sep 12 00:53:38 2013(r255486) @@ -28,7 +28,7 @@ .\ @(#)close.28.2 (Berkeley) 4/19/94 .\ $FreeBSD$ .\ -.Dd January 22, 2012 +.Dd September 11, 2013 .Dt CLOSE 2 .Os .Sh NAME @@ -39,7 +39,7 @@ .Sh SYNOPSIS .In unistd.h .Ft int -.Fn close int d +.Fn close int fd .Sh DESCRIPTION The .Fn close @@ -107,7 +107,7 @@ system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The -.Fa d +.Fa fd argument is not an active descriptor. .It Bq Er EINTR Modified: head/lib/libc/sys/ioctl.2 == --- head/lib/libc/sys/ioctl.2 Thu Sep 12 00:46:32 2013(r255485) +++ head/lib/libc/sys/ioctl.2 Thu Sep 12 00:53:38 2013(r255486) @@ -29,7 +29,7 @@ .\ .\ $FreeBSD$ .\ -.Dd May 11, 2010 +.Dd September 11, 2013 .Dt IOCTL 2 .Os .Sh NAME @@ -40,7 +40,7 @@ .Sh SYNOPSIS .In sys/ioctl.h .Ft int -.Fn ioctl int d unsigned long request ... +.Fn ioctl int fd unsigned long request ... .Sh DESCRIPTION The .Fn ioctl @@ -51,7 +51,7 @@ may be controlled with .Fn ioctl requests. The argument -.Fa d +.Fa fd must be an open file descriptor. .Pp The third argument to @@ -116,19 +116,19 @@ will fail if: .Bl -tag -width Er .It Bq Er EBADF The -.Fa d +.Fa fd argument is not a valid descriptor. .It Bq Er ENOTTY The -.Fa d +.Fa fd argument is not associated with a character special device. .It Bq Er ENOTTY The specified request does not apply to the kind of object that the descriptor -.Fa d +.Fa fd references. .It Bq Er EINVAL The Modified: head/lib/libc/sys/read.2 == --- head/lib/libc/sys/read.2Thu Sep 12 00:46:32 2013(r255485) +++ head/lib/libc/sys/read.2Thu Sep 12 00:53:38 2013(r255486) @@ -28,7 +28,7 @@ .\ @(#)read.2 8.4 (Berkeley) 2/26/94 .\ $FreeBSD$ .\ -.Dd January 22, 2012 +.Dd September 11, 2013 .Dt READ 2 .Os .Sh NAME @@ -43,14 +43,14 @@ .In sys/types.h .In unistd.h .Ft ssize_t -.Fn read int d void *buf size_t nbytes +.Fn read int fd void *buf size_t nbytes .Ft ssize_t -.Fn pread int d void *buf size_t nbytes off_t offset +.Fn pread int fd void *buf size_t nbytes off_t offset .In sys/uio.h .Ft ssize_t -.Fn readv int d const struct iovec *iov int iovcnt +.Fn readv int fd const struct iovec *iov int iovcnt .Ft ssize_t -.Fn preadv int d const struct iovec *iov int iovcnt off_t offset +.Fn preadv int fd const struct iovec *iov int iovcnt off_t offset .Sh DESCRIPTION The .Fn read @@ -58,7 +58,7 @@ system call attempts to read .Fa nbytes of data from the object referenced by the descriptor -.Fa d +.Fa fd into the buffer pointed to by .Fa buf . The @@ -107,7 +107,7 @@ On objects capable of seeking, the .Fn read starts at a position given by the pointer associated with -.Fa d +.Fa fd (see .Xr lseek 2 ) . Upon return from @@
