LU-11380 llapi: separate FID man pages

Add separate man pages for the lfs commands and llapi functions.

Test-Parameters: trivial
Signed-off-by: Andreas Dilger <adilger@whamcloud.com>
Change-Id: I05abfaf888a5474d62feebab4e8db543ba3ebbe5
Reviewed-on: https://review.whamcloud.com/35673
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Emoly Liu <emoly@whamcloud.com>
Reviewed-by: Ben Evans <bevans@cray.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am
index 6c65c76..08a069e 100644 (file)
--- a/lustre/doc/Makefile.am
+++ b/lustre/doc/Makefile.am
@@ -41,6 +41,7 @@ MANFILES =                                    \
        ldev.conf.5                             \
        lfs.1                                   \
        lfs-df.1                                \
        ldev.conf.5                             \
        lfs.1                                   \
        lfs-df.1                                \

+       lfs-fid2path.1                          \

        lfs-find.1                              \
        lfs-getstripe.1                         \
        lfs-getdirstripe.1                      \
        lfs-find.1                              \
        lfs-getstripe.1                         \
        lfs-getdirstripe.1                      \


@@ -55,11 +56,12 @@ MANFILES =                                  \
        lfs-mirror-split.1                      \
        lfs-mirror-verify.1                     \
        lfs-mkdir.1                             \
        lfs-mirror-split.1                      \
        lfs-mirror-verify.1                     \
        lfs-mkdir.1                             \

+       lfs-path2fid.1                          \

        lfs-pcc.1                               \
        lfs-pcc.1                               \

+       lfs-project.1                           \

        lfs-setdirstripe.1                      \
        lfs-setstripe.1                         \
        lfs-setquota.1                          \
        lfs-setdirstripe.1                      \
        lfs-setstripe.1                         \
        lfs-setquota.1                          \

-       lfs-project.1                           \

        l_getidentity.8                         \
        lgss_sk.8                               \
        lhbadm.8                                \
        l_getidentity.8                         \
        lgss_sk.8                               \
        lhbadm.8                                \

diff --git a/lustre/doc/lfs-fid2path.1 b/lustre/doc/lfs-fid2path.1
new file mode 100644 (file)
index 0000000..1b142fd
--- /dev/null
+++ b/lustre/doc/lfs-fid2path.1
@@ -0,0 +1,36 @@
+.TH lfs-fid2path 1 "2018-11-24" Lustre "user utilities"
+.SH NAME
+lfs fid2path \- print the pathname(s) for a file identifier
+.SH SYNOPSIS
+.BR "lfs fid2path " [ --current | -c "] [" --link | -l
+.RI < linkno ">] <" fsname | rootpath "> <" fid "> ...
+.SH DESCRIPTION
+.B lfs fid2path
+maps a numeric Lustre File IDentifier (FID) to one or more pathnames that
+have hard links to that file.  This allows resolving filenames for FIDs used
+in console error messages, and resolving all of the pathnames for a file
+that has multiple hard links.  Pathnames are resolved relative to the
+.I rootpath
+specified, or relative to the filesystem mountpoint if
+.I fsname
+is provided.
+.SH OPTIONS
+.TP
+.BR --current | -c
+Print the current link number with each pathname or parent directory.
+.TP
+.BR --link | -l
+If a file has multiple hard links, then print only the specified link number,
+starting at link 0.  If multiple FIDs are given, but only one
+pathname is needed for each file, use
+.BR "--link 0" .
+.SH EXAMPLES
+.TP
+.B $ lfs fid2path /mnt/testfs [0x200000403:0x11f:0x0]
+/mnt/testfs/etc/hosts
+.SH SEE ALSO
+.BR lfs (1),
+.BR lfs-getstripe (1),
+.BR lfs-path2fid (1),
+.BR llapi_fid2path (3),
+.BR lustre (7)

diff --git a/lustre/doc/lfs-path2fid.1 b/lustre/doc/lfs-path2fid.1
new file mode 100644 (file)
index 0000000..22e4b65
--- /dev/null
+++ b/lustre/doc/lfs-path2fid.1
@@ -0,0 +1,36 @@
+.TH lfs-path2fid 1 "2018-11-24" Lustre "user utilities"
+.SH NAME
+lfs path2fid \- print the file identifier for a given pathname
+.SH SYNOPSIS
+.BR "lfs path2fid " [ --parents ]
+.RI < directory | file > ...
+.SH DESCRIPTION
+.B lfs path2fid
+prints the File Identifier for the specified
+.I file
+or
+.IR directory .
+The FID is unique for each file in the filesystem, and is never reused
+for other files if the file is deleted.
+.br
+The FID is also available for regular files via
+.BR "lfs getstripe -F".
+.SH OPTIONS
+.TP
+.B --parents
+Print out the parent FID and name(s) of the given entries. If an entry has
+multiple links, these are displayed on a single line, tab-separated.
+.SH EXAMPLES
+.TP
+.B $ lfs path2fid /mnt/lustre/etc/hosts
+[0x200000403:0x11f:0x0]
+.TP
+.B $ lfs path2fid --parents /mnt/lustre/etc/hosts
+[0x200000403:0x101:0x0]/hosts
+.SH SEE ALSO
+.BR lfs (1),
+.BR lfs-fid2path (1),
+.BR lfs-getstripe (1),
+.BR llapi_path2fid (3),
+.BR llapi_path2parent (3),
+.BR lustre (7)

diff --git a/lustre/doc/lfs.1 b/lustre/doc/lfs.1
index d508e0d..f85cc3e 100644 (file)
--- a/lustre/doc/lfs.1
+++ b/lustre/doc/lfs.1
@@ -192,21 +192,6 @@ List all the OSTs for all mounted filesystems. If a \fBpath\fR is provided
 that is located on a lustre mounted file system then only the OSTs belonging
 to that filesystem are displayed.
 .TP
 that is located on a lustre mounted file system then only the OSTs belonging
 to that filesystem are displayed.
 .TP

-.B fid2path [--link <linkno>] <fsname|rootpath> <fid> ...
-Print out the pathname(s) for the specified \fIfid\fR(s) from the filesystem
-mounted at \fBrootpath\fR or named \fBfsname\fR.  If a file has multiple
-hard links, then all of the pathnames for that file are printed, unless
-\fB--link\fR limits the printing to only the specified link number (starting
-at 0, in no particular order).  If multiple fids are specified, but only a
-single pathname is needed for each file, use \fB--link 0\fR.
-.TP
-.B path2fid [--parents] <path> ...
-Print out the FIDs for the specified \fBpath(s)\fR.  If multiple pathnames
-are given, then they will be printed one per line with the path as prefix.
-The \fB--parents\fR switch makes it output the parent FID and name(s) of the
-given entries. If an entry has multiple links, these are displayed on a single
-line, tab-separated.
-.TP

 .B pool_list
 .RI { filesystem }[ .poolname "] | {" pathname }
 List the pools in
 .B pool_list
 .RI { filesystem }[ .poolname "] | {" pathname }
 List the pools in


@@ -307,6 +292,7 @@ The lfs command is part of the Lustre filesystem.
 .SH SEE ALSO
 .BR lctl (8),
 .BR lfs-df (1),
 .SH SEE ALSO
 .BR lctl (8),
 .BR lfs-df (1),

+.BR lfs-fid2path (1),

 .BR lfs-find (1),
 .BR lfs-getdirstripe (1),
 .BR lfs-getname (1),
 .BR lfs-find (1),
 .BR lfs-getdirstripe (1),
 .BR lfs-getname (1),


@@ -316,6 +302,7 @@ The lfs command is part of the Lustre filesystem.
 .BR lfs-migrate (1),
 .BR lfs_migrate (1),
 .BR lfs-project (1),
 .BR lfs-migrate (1),
 .BR lfs_migrate (1),
 .BR lfs-project (1),

+.BR lfs-path2fid (1),

 .BR lfs-setdirstripe (1),
 .BR lfs-setquota (1),
 .BR lfs-setstripe (1),
 .BR lfs-setdirstripe (1),
 .BR lfs-setquota (1),
 .BR lfs-setstripe (1),

diff --git a/lustre/doc/llapi_path2fid.3 b/lustre/doc/llapi_path2fid.3
index eb077b6..695aa31 100644 (file)
--- a/lustre/doc/llapi_path2fid.3
+++ b/lustre/doc/llapi_path2fid.3
@@ -1,11 +1,11 @@
-.TH llapi_path2fid 3 "2014 Mar 18" "Lustre User API"
+.TH llapi_path2fid 3 "2018-11-28" "Lustre User API"

 .SH NAME
 .SH NAME

-llapi_path2fid \- translate a path name to a Lustre FID
+llapi_path2fid \- translate a path name to a File Identifier

 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
 .PP
 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
 .PP

-.BI "int llapi_path2fid(const char *"path ", struct lu_fid *"fid );
+.BI "int llapi_path2fid(const char *" path ", struct lu_fid *" fid );

 .fi
 .SH DESCRIPTION
 .PP
 .fi
 .SH DESCRIPTION
 .PP


@@ -17,15 +17,19 @@ into
 .IR fid .
 The
 .I fid
 .IR fid .
 The
 .I fid

-may be then be passed to other llapi functions that expect the
+may be then be passed to other
+.B llapi_
+functions that expect the

 .B struct lu_fid
 data type.
 .SH RETURN VALUES
 .LP
 .B struct lu_fid
 data type.
 .SH RETURN VALUES
 .LP

-.B llapi_path2fid()

 returns 0 on success or a negative errno value on failure.
 .SH ERRORS
 .TP 15
 returns 0 on success or a negative errno value on failure.
 .SH ERRORS
 .TP 15

+.SM -EINVAL
+An invalid argument was specified.
+.TP

 .SM -ENOTTY
 .I path
 does not reside on a Lustre filesystem.
 .SM -ENOTTY
 .I path
 does not reside on a Lustre filesystem.


@@ -33,10 +37,9 @@ does not reside on a Lustre filesystem.
 .SM -ENOENT
 .I path
 does not exist.
 .SM -ENOENT
 .I path
 does not exist.

-.TP
-.SM -EINVAL
-An invalid argument was specified.
-.SH "SEE ALSO"
+.SH SEE ALSO

 .BR llapi_layout_get_by_fid (3),
 .BR llapi_layout (7),
 .BR llapi_layout_get_by_fid (3),
 .BR llapi_layout (7),

+.BR llapi_fid2path (3),
+.BR llapi_path2parent (3),

 .BR lustreapi (7)
 .BR lustreapi (7)

diff --git a/lustre/doc/llapi_path2parent.3 b/lustre/doc/llapi_path2parent.3
index 5328206..cd8b613 100644 (file)
--- a/lustre/doc/llapi_path2parent.3
+++ b/lustre/doc/llapi_path2parent.3
@@ -22,29 +22,31 @@ for link number
 .I linkno
 stores the FID of the parent directory into
 .I parent_fid
 .I linkno
 stores the FID of the parent directory into
 .I parent_fid

-and the zero-terminated name of the entry into the buffer
+and the NUL-terminated name of the entry into the buffer

 .I name
 which is expected to be of size
 .IR name_size .
 .I name
 which is expected to be of size
 .IR name_size .

-
-The function
+If
+.I linkno
+should be initialized to
+.B -1
+when starting to iterate over all links of a file.  The function

 .B llapi_fd2parent()
 behaves similarly except that it operates on an open file descriptor
 instead of a path.
 .sp
 .SH RETURN VALUES
 .LP
 .B llapi_fd2parent()
 behaves similarly except that it operates on an open file descriptor
 instead of a path.
 .sp
 .SH RETURN VALUES
 .LP

-.B llapi_path2fid()
-and
-.B llapi_fd2fid()
-return 0 on success or a negative errno value on failure.
+0 is returned on success or a negative errno value on failure.

 .SH ERRORS
 .TP 15
 .SM -ENODATA
 .SH ERRORS
 .TP 15
 .SM -ENODATA

-linkno has reached the link count.
+linkno has reached the total link count of the file.

 .TP
 .SM -ENOTTY
 .I path
 .TP
 .SM -ENOTTY
 .I path

+or
+.I fd

 does not reside on a Lustre filesystem.
 .TP
 .SM -ENOENT
 does not reside on a Lustre filesystem.
 .TP
 .SM -ENOENT


@@ -55,9 +57,12 @@ does not exist.
 An invalid argument was specified.
 .TP
 .SM -EOVERFLOW
 An invalid argument was specified.
 .TP
 .SM -EOVERFLOW

-The given buffer was too small.
+The given buffer was too small to hold the pathname.

 .TP
 .SM -EPERM
 The file cannot be open by user or CAP_DAC_READ_SEARCH is not granted.
 .SH "SEE ALSO"
 .TP
 .SM -EPERM
 The file cannot be open by user or CAP_DAC_READ_SEARCH is not granted.
 .SH "SEE ALSO"

+.BR lfs-path2fid (1),
+.BR llapi_fid2path (3),
+.BR llapi_path2fid (3),

 .BR lustreapi (7)
 .BR lustreapi (7)

diff --git a/lustre/doc/lustreapi.7 b/lustre/doc/lustreapi.7
index 78f13e6..b733832 100644 (file)
--- a/lustre/doc/lustreapi.7
+++ b/lustre/doc/lustreapi.7
@@ -11,12 +11,16 @@ settings specific to the Lustre filesystem (allocation policies,
 quotas, file layouts, etc).  See the referenced man pages for details.
 .SH SEE ALSO
 .sp
 quotas, file layouts, etc).  See the referenced man pages for details.
 .SH SEE ALSO
 .sp

+.BR llapi_create_volatile_param (3),

 .BR llapi_fd2parent (3),
 .BR llapi_fd2parent (3),

+.BR llapi_fid2path (3),

 .BR llapi_file_create (3),
 .BR llapi_file_get_stripe (3),
 .BR llapi_file_open (3),
 .BR llapi_group_lock (3),
 .BR llapi_group_unlock (3),
 .BR llapi_file_create (3),
 .BR llapi_file_get_stripe (3),
 .BR llapi_file_open (3),
 .BR llapi_group_lock (3),
 .BR llapi_group_unlock (3),

+.BR llapi_heat_get (3),
+.BR llapi_heat_set (3),

 .BR llapi_hsm_action_begin (3),
 .BR llapi_hsm_action_end (3),
 .BR llapi_hsm_action_get_dfid (3),
 .BR llapi_hsm_action_begin (3),
 .BR llapi_hsm_action_end (3),
 .BR llapi_hsm_action_get_dfid (3),


@@ -48,6 +52,7 @@ quotas, file layouts, etc).  See the referenced man pages for details.
 .BR llapi_layout_get_by_fd (3),
 .BR llapi_layout_get_by_fid (3),
 .BR llapi_layout_get_by_path (3),
 .BR llapi_layout_get_by_fd (3),
 .BR llapi_layout_get_by_fid (3),
 .BR llapi_layout_get_by_path (3),

+.BR llapi_layout_get_by_xattr (3),

 .BR llapi_layout_ost_index_get (3),
 .BR llapi_layout_ost_index_set (3),
 .BR llapi_layout_pattern_get (3),
 .BR llapi_layout_ost_index_get (3),
 .BR llapi_layout_ost_index_set (3),
 .BR llapi_layout_pattern_get (3),

diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c
index 924479f..62f9198 100644 (file)
--- a/lustre/utils/lfs.c
+++ b/lustre/utils/lfs.c
@@ -557,9 +557,7 @@ command_t cmdlist[] = {
        {"fid2path", lfs_fid2path, 0,
         "Resolve the full path(s) for given FID(s). For a specific hardlink "
         "specify link number <linkno>.\n"
        {"fid2path", lfs_fid2path, 0,
         "Resolve the full path(s) for given FID(s). For a specific hardlink "
         "specify link number <linkno>.\n"

-       /* "For a historical link name, specify changelog record <recno>.\n" */
-        "usage: fid2path [--link <linkno>] <fsname|rootpath> <fid> ..."
-               /* [ --rec <recno> ] */ },
+        "usage: fid2path [-c] [--link|-l <linkno>] <fsname|root> <fid> ..."},

        {"path2fid", lfs_path2fid, 0, "Display the fid(s) for a given path(s).\n"
         "usage: path2fid [--parents] <path> ..."},
        {"rmfid", lfs_rmfid, 0, "Remove file(s) by FID(s)\n"
        {"path2fid", lfs_path2fid, 0, "Display the fid(s) for a given path(s).\n"
         "usage: path2fid [--parents] <path> ..."},
        {"rmfid", lfs_rmfid, 0, "Remove file(s) by FID(s)\n"