[PING] manual: Complete @standards in filesys.texi.

[Rical Jasan <ricaljasan at pacific dot net>]

Ping.

I recently retread this ground with all the standards documentation I've
been able to dredge up so far, and wound up with the same results.
(There is also confirmation for some of these from Zack. [0])

The only annotation I question is the use of the conditional expression
for posix_fallocate64.  The second time around I simply wrote it as
"LFS", because I couldn't find a reference to it anywhere in POSIX.  Is
that sufficient?  For a *64 function marked LFS, we could expect one to
look at the non-64 version for the original standard.  They'll also show
up next to each other in the Summary, so the information will be there,
at a glance.

Rical

[0] https://sourceware.org/ml/libc-alpha/2016-12/msg00148.html

On 06/16/2017 04:09 AM, Rical Jasan wrote:
> 	* manual/filesys.texi (DT_UNKNOWN): Add header and standard
> 	annotation.
> 	(DT_REG): Likewise.
> 	(DT_DIR): Likewise.
> 	(DT_FIFO): Likewise.
> 	(DT_SOCK): Likewise.
> 	(DT_CHR): Likewise.
> 	(DT_BLK): Likewise.
> 	(DT_LNK): Likewise.
> 	(FTW_F): Likewise.
> 	(FTW_D): Likewise.
> 	(FTW_NS): Likewise.
> 	(FTW_DNR): Likewise.
> 	(FTW_SL): Likewise.
> 	(FTW_DP): Likewise.
> 	(FTW_SLN): Likewise.
> 	(FTW_PHYS): Likewise.
> 	(FTW_MOUNT): Likewise.
> 	(FTW_CHDIR): Likewise.
> 	(FTW_DEPTH): Likewise.
> 	(FTW_ACTIONRETVAL): Likewise.
> 	(posix_fallocate): Likewise.
> 	(posix_fallocate64): Likewise.
> ---
>  manual/filesys.texi | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
> 
> diff --git a/manual/filesys.texi b/manual/filesys.texi
> index 5f7eb0e231..ed0e75bfd2 100644
> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -280,28 +280,36 @@ are defined for its value:
>  
>  @vtable @code
>  @item DT_UNKNOWN
> +@standards{BSD, dirent.h}
>  The type is unknown.  Only some filesystems have full support to
>  return the type of the file, others might always return this value.
>  
>  @item DT_REG
> +@standards{BSD, dirent.h}
>  A regular file.
>  
>  @item DT_DIR
> +@standards{BSD, dirent.h}
>  A directory.
>  
>  @item DT_FIFO
> +@standards{BSD, dirent.h}
>  A named pipe, or FIFO.  @xref{FIFO Special Files}.
>  
>  @item DT_SOCK
> +@standards{BSD, dirent.h}
>  A local-domain socket.  @c !!! @xref{Local Domain}.
>  
>  @item DT_CHR
> +@standards{BSD, dirent.h}
>  A character device.
>  
>  @item DT_BLK
> +@standards{BSD, dirent.h}
>  A block device.
>  
>  @item DT_LNK
> +@standards{BSD, dirent.h}
>  A symbolic link.
>  @end vtable
>  
> @@ -865,16 +873,21 @@ file.  It can have the following values:
>  
>  @vtable @code
>  @item FTW_F
> +@standards{SVID, ftw.h}
>  The item is either a normal file or a file which does not fit into one
>  of the following categories.  This could be special files, sockets etc.
>  @item FTW_D
> +@standards{SVID, ftw.h}
>  The item is a directory.
>  @item FTW_NS
> +@standards{SVID, ftw.h}
>  The @code{stat} call failed and so the information pointed to by the
>  second parameter is invalid.
>  @item FTW_DNR
> +@standards{SVID, ftw.h}
>  The item is a directory which cannot be read.
>  @item FTW_SL
> +@standards{XPG4.2, ftw.h}
>  The item is a symbolic link.  Since symbolic links are normally followed
>  seeing this value in a @code{ftw} callback function means the referenced
>  file does not exist.  The situation for @code{nftw} is different.
> @@ -917,10 +930,12 @@ type.  However for the third argument some additional values are defined
>  to allow finer differentiation:
>  @vtable @code
>  @item FTW_DP
> +@standards{XPG4.2, ftw.h}
>  The current item is a directory and all subdirectories have already been
>  visited and reported.  This flag is returned instead of @code{FTW_D} if
>  the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below).
>  @item FTW_SLN
> +@standards{XPG4.2, ftw.h}
>  The current item is a stale symbolic link.  The file it points to does
>  not exist.
>  @end vtable
> @@ -1063,25 +1078,30 @@ is @math{0} or a bitwise-OR combination of any of the following values.
>  
>  @vtable @code
>  @item FTW_PHYS
> +@standards{XPG4.2, ftw.h}
>  While traversing the directory symbolic links are not followed.  Instead
>  symbolic links are reported using the @code{FTW_SL} value for the type
>  parameter to the callback function.  If the file referenced by a
>  symbolic link does not exist @code{FTW_SLN} is returned instead.
>  @item FTW_MOUNT
> +@standards{XPG4.2, ftw.h}
>  The callback function is only called for items which are on the same
>  mounted filesystem as the directory given by the @var{filename}
>  parameter to @code{nftw}.
>  @item FTW_CHDIR
> +@standards{XPG4.2, ftw.h}
>  If this flag is given the current working directory is changed to the
>  directory of the reported object before the callback function is called.
>  When @code{ntfw} finally returns the current directory is restored to
>  its original value.
>  @item FTW_DEPTH
> +@standards{XPG4.2, ftw.h}
>  If this option is specified then all subdirectories and files within
>  them are processed before processing the top directory itself
>  (depth-first processing).  This also means the type flag given to the
>  callback function is @code{FTW_DP} and not @code{FTW_D}.
>  @item FTW_ACTIONRETVAL
> +@standards{GNU, ftw.h}
>  If this option is specified then return values from callbacks
>  are handled differently.  If the callback returns @code{FTW_CONTINUE},
>  walking continues normally.  @code{FTW_STOP} means walking stops
> @@ -3136,6 +3156,7 @@ writes to memory-mapped regions created with @code{mmap} can still
>  result in @code{SIGBUS}.
>  
>  @deftypefun int posix_fallocate (int @var{fd}, off_t @var{offset}, off_t @var{length})
> +@standards{POSIX.1-2001, fcntl.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>  @c If the file system does not support allocation,
>  @c @code{posix_fallocate} has a race with file extension (if
> @@ -3194,6 +3215,7 @@ allocation.  Instead, an @code{EOPNOTSUPP} is returned to the caller.
>  @end deftypefun
>  
>  @deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{offset}, off64_t @var{length})
> +@standards{POSIX.1-2001 && LFS, fcntl.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>  
>  This function is a variant of @code{posix_fallocate64} which accepts