xfs
[Top] [All Lists]

[PATCH] libhandle: document the need for path_to_handle

To: xfs@xxxxxxxxxxx
Subject: [PATCH] libhandle: document the need for path_to_handle
From: tinguely@xxxxxxx
Date: Thu, 09 Apr 2015 08:31:04 -0500
Delivered-to: xfs@xxxxxxxxxxx
References: <1504091316590.18609@xxxxxxxxxxxxxxxxxxxxxxxxx>
User-agent: quilt/0.51-1
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),


<Prev in Thread] Current Thread [Next in Thread>