From: Andreas Dilger Date: Tue, 9 Jul 2019 06:34:47 +0000 (-0600) Subject: LU-11380 llapi: separate FID man pages X-Git-Tag: 2.12.90~100 X-Git-Url: https://git.whamcloud.com/?p=fs%2Flustre-release.git;a=commitdiff_plain;h=253cc7ae49f89bba919a5a570209e2629b3843c6 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 Change-Id: I05abfaf888a5474d62feebab4e8db543ba3ebbe5 Reviewed-on: https://review.whamcloud.com/35673 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Emoly Liu Reviewed-by: Ben Evans Reviewed-by: Oleg Drokin --- diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index 6c65c76..08a069e 100644 --- a/lustre/doc/Makefile.am +++ b/lustre/doc/Makefile.am @@ -41,6 +41,7 @@ MANFILES = \ ldev.conf.5 \ lfs.1 \ lfs-df.1 \ + lfs-fid2path.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-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 \ diff --git a/lustre/doc/lfs-fid2path.1 b/lustre/doc/lfs-fid2path.1 new file mode 100644 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 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 --- 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 -.B fid2path [--link ] ... -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] ... -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 @@ -307,6 +292,7 @@ The lfs command is part of the Lustre filesystem. .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), @@ -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-path2fid (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 --- 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 -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 .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 @@ -17,15 +17,19 @@ into .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. @@ -33,10 +37,9 @@ 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) diff --git a/lustre/doc/llapi_path2parent.3 b/lustre/doc/llapi_path2parent.3 index 5328206..cd8b613 100644 --- 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 -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 @@ -55,9 +57,12 @@ does not exist. 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) diff --git a/lustre/doc/lustreapi.7 b/lustre/doc/lustreapi.7 index 78f13e6..b733832 100644 --- 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 +.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), @@ -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_xattr (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 --- 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 .\n" - /* "For a historical link name, specify changelog record .\n" */ - "usage: fid2path [--link ] ..." - /* [ --rec ] */ }, + "usage: fid2path [-c] [--link|-l ] ..."}, {"path2fid", lfs_path2fid, 0, "Display the fid(s) for a given path(s).\n" "usage: path2fid [--parents] ..."}, {"rmfid", lfs_rmfid, 0, "Remove file(s) by FID(s)\n"