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>
ldev.conf.5 \
lfs.1 \
lfs-df.1 \
+ lfs-fid2path.1 \
lfs-find.1 \
lfs-getstripe.1 \
lfs-getdirstripe.1 \
lfs-mirror-split.1 \
lfs-mirror-verify.1 \
lfs-mkdir.1 \
+ lfs-path2fid.1 \
lfs-pcc.1 \
+ lfs-project.1 \
lfs-setdirstripe.1 \
lfs-setstripe.1 \
lfs-setquota.1 \
- lfs-project.1 \
l_getidentity.8 \
lgss_sk.8 \
lhbadm.8 \
--- /dev/null
+.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)
--- /dev/null
+.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)
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
.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-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),
-.TH llapi_path2fid 3 "2014 Mar 18" "Lustre User API"
+.TH llapi_path2fid 3 "2018-11-28" "Lustre User API"
.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
-.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
.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 llapi_path2fid()
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 -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_fid2path (3),
+.BR llapi_path2parent (3),
.BR lustreapi (7)
.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 .
-
-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_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
-linkno has reached the link count.
+linkno has reached the total link count of the file.
.TP
.SM -ENOTTY
.I path
+or
+.I fd
does not reside on a Lustre filesystem.
.TP
.SM -ENOENT
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"
+.BR lfs-path2fid (1),
+.BR llapi_fid2path (3),
+.BR llapi_path2fid (3),
.BR lustreapi (7)
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_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_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_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),
{"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"
git://git.whamcloud.com / fs / lustre-release.git / commitdiff