manual: Document the linkat function

Message ID 20171103213712.ED59B41F1E4EF@oldenburg.str.redhat.com
State New
Headers show
Series
  • manual: Document the linkat function
Related show

Commit Message

Florian Weimer Nov. 3, 2017, 9:37 p.m.
2017-11-03  Florian Weimer  <fweimer@redhat.com>

	* manual/filesys.texi (Hard Links): Document linkat.

Comments

Jonathan Nieder Nov. 3, 2017, 9:52 p.m. | #1
Hi,

Florian Weimer wrote:

> 2017-11-03  Florian Weimer  <fweimer@redhat.com>
>
> 	* manual/filesys.texi (Hard Links): Document linkat.

Yay, thanks for writing this.

> --- a/manual/filesys.texi
> +++ b/manual/filesys.texi
> @@ -1205,6 +1205,35 @@ A hardware error occurred while trying to read or write the to filesystem.
>  @end table
>  @end deftypefun
>  
> +@deftypefun int linkat (int olfd, const char *@var{oldname}, int newfd, const char *@var{newname}, int flags)

s/olfd/oldfd/

[...]
> +@table @code
> +@item AT_SYMLINK_FOLLOW
> +If the source path denoted by @var{oldfd} and @var{oldname} is a
> +symbolic link, @code{linkat} follows the symbolic link and creates a

usage nit: "denoted" does not seem like the right word.  Maybe
"identified", to match the wording used above?  Or perhaps something
like the following:

	If the file @{oldname} in the directory associated to @var{oldfd}
	is a symbolic link, @code{linkat} follows the ...

> +link to its target.  If the flag is not set, a link for the symbolic
> +link itself is created; this is not supported by all file systems and
> +@code{linkat} can fail in this case.
> +
> +@item AT_EMPTY_PATH
> +If this flag is specified, @var{oldname} can be an empty string.  In
> +this case, a new link to the file denoted by the descriptor @var{oldfd}
> +is created, which may have been opened with @code{O_PATH} or
> +@code{O_TMPFILE}.  This flag is a GNU extension.
> +@end table
> +@end deftypefun
> +
>  @node Symbolic Links
>  @section Symbolic Links
>  @cindex soft link
> @@ -3515,7 +3544,6 @@ The @code{mkdtemp} function comes from OpenBSD.
>  @c fchownat
>  @c futimesat
>  @c fstatat (there's a commented-out safety assessment for this one)
> -@c linkat
>  @c mkdirat
>  @c mkfifoat
>  @c name_to_handle_at

With whatever subset of the tweaks suggested above seems sensible,
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks.
Florian Weimer Nov. 3, 2017, 11:29 p.m. | #2
On 11/03/2017 10:52 PM, Jonathan Nieder wrote:

>> --- a/manual/filesys.texi
>> +++ b/manual/filesys.texi
>> @@ -1205,6 +1205,35 @@ A hardware error occurred while trying to read or write the to filesystem.
>>   @end table
>>   @end deftypefun
>>   
>> +@deftypefun int linkat (int olfd, const char *@var{oldname}, int newfd, const char *@var{newname}, int flags)
> 
> s/olfd/oldfd/

Thanks, fixed.

> [...]
>> +@table @code
>> +@item AT_SYMLINK_FOLLOW
>> +If the source path denoted by @var{oldfd} and @var{oldname} is a
>> +symbolic link, @code{linkat} follows the symbolic link and creates a
> 
> usage nit: "denoted" does not seem like the right word.  Maybe
> "identified", to match the wording used above?

Okay, let's use identified.

> Or perhaps something
> like the following:
> 
> 	If the file @{oldname} in the directory associated to @var{oldfd}
> 	is a symbolic link, @code{linkat} follows the ...

That's not quite accurate because the name does not have to be located 
in that directory, it is only resolved relative to it.

> With whatever subset of the tweaks suggested above seems sensible,
> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Pushed with the changes above.

Thanks,
Florian

Patch

diff --git a/manual/filesys.texi b/manual/filesys.texi
index 5f7eb0e231..a364c373b2 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -1205,6 +1205,35 @@  A hardware error occurred while trying to read or write the to filesystem.
 @end table
 @end deftypefun
 
+@deftypefun int linkat (int olfd, const char *@var{oldname}, int newfd, const char *@var{newname}, int flags)
+@standards{POSIX.1, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The @code{linkat} function is analogous to the @code{link} function,
+except that it identifies its source and target using a combination of a
+file descriptor (referring to a directory) and a pathname.  If a
+pathnames is not absolute, it is resolved relative to the corresponding
+file descriptor.  The special file descriptor @code{AT_FDCWD} denotes
+the current directory.
+
+The @var{flags} argument is a combination of the following flags:
+
+@table @code
+@item AT_SYMLINK_FOLLOW
+If the source path denoted by @var{oldfd} and @var{oldname} is a
+symbolic link, @code{linkat} follows the symbolic link and creates a
+link to its target.  If the flag is not set, a link for the symbolic
+link itself is created; this is not supported by all file systems and
+@code{linkat} can fail in this case.
+
+@item AT_EMPTY_PATH
+If this flag is specified, @var{oldname} can be an empty string.  In
+this case, a new link to the file denoted by the descriptor @var{oldfd}
+is created, which may have been opened with @code{O_PATH} or
+@code{O_TMPFILE}.  This flag is a GNU extension.
+@end table
+@end deftypefun
+
 @node Symbolic Links
 @section Symbolic Links
 @cindex soft link
@@ -3515,7 +3544,6 @@  The @code{mkdtemp} function comes from OpenBSD.
 @c fchownat
 @c futimesat
 @c fstatat (there's a commented-out safety assessment for this one)
-@c linkat
 @c mkdirat
 @c mkfifoat
 @c name_to_handle_at