| Message ID | 20171103213712.ED59B41F1E4EF@oldenburg.str.redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | manual: Document the linkat function | expand |
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.
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
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