The handle ioctls require an open file descriptor to
the XFS mount directory. This file descriptor is found
and supplied in the libhandle code by matching the
entry added with a path_to_handle() call. Document
the requirement and supply a simple example.
Signed-off-by: Mark Tinguely <tinguely@xxxxxxx>
---
man/man3/handle.3 | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 69 insertions(+), 1 deletion(-)
Index: b/man/man3/handle.3
===================================================================
--- a/man/man3/handle.3
+++ b/man/man3/handle.3
@@ -74,6 +74,12 @@ The
function returns the handle for the filesystem in which the object given by the
.I path
argument resides.
+.I path
+must be the path to the mount point or
+.BR open_by_handle ()
+will return the
+.B ENOTDIR
+error.
.PP
The
.BR fd_to_handle ()
@@ -95,7 +101,16 @@ The
function opens a file descriptor for the object referenced by a handle.
It is analogous and identical to
.BR open (2)
-with the exception of accepting handles instead of path names.
+with the exception of accepting handles instead of path names. The returned
+file descriptor is opened to do invisible IO. Internally,
+.BR open_by_handle ()
+uses the mount point file descriptor that was saved by
+.BR path_to_fshandle ().
+Therefore,
+.BR path_to_fshandle ().
+must be called before calling
+.BR open_by_handle ().
+See below for an example.
.PP
The
.BR readlink_by_handle ()
@@ -192,6 +207,59 @@ does not exist.
.TP
.B EPERM
The caller does not have sufficient privileges.
+.SH EXAMPLE
+Example of
+.BR open_by_handle ().
+.PP
+.Vb 1
+\& main()
+.br
+\& {
+.br
+\& int fd;
+.br
+\& size_t hlen;
+.br
+\& void *han;
+.br
+\& size_t sz_int_used;
+.br
+\& void *hdl_int_used;
+.br
+\& char *mount_path = "/mnt/";
+.br
+\& char *file = "file_to_open";
+.br
+\& if (path_to_handle(file, &han, &hlen) < 0) {
+.br
+\& perror("path-to-handle");
+.br
+\& exit(1);
+.br
+\& }
+.br
+\& /*
+.br
+\& * path_to_fshandle saves an internal copy of the mount point's
+.br
+\& * (/mnt in this example) file descriptor. The open_by_handle call
+.br
+\& * looks up this internal file descriptor and uses it in the
+.br
+\& * xfsctl call to the kernel. Once path_to_fshandle is called,
+.br
+\& * this internal file descriptor remains open for the remaining
+.br
+\& * life of the application.
+.br
+\& */
+.br
+\& path_to_fshandle(mount_path, &hdl_int_used, &sz_int_used);
+.br
+\& fd = open_by_handle(han, hlen, O_RDWR);
+.br
+\&}
+.Ve
.SH SEE ALSO
.BR open (2),
.BR readlink (2),
_______________________________________________
xfs mailing list
xfs@xxxxxxxxxxx
http://oss.sgi.com/mailman/listinfo/xfs
