[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
 .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 ().
+.BR path_to_fshandle ().
+must be called before calling
+.BR open_by_handle ().
+See below for an example.
 .BR readlink_by_handle ()
@@ -192,6 +207,59 @@ does not exist.
 The caller does not have sufficient privileges.
+Example of
+.BR open_by_handle ().
+.Vb 1
+\& main()
+\& {
+\&     int fd;
+\&     size_t hlen;
+\&     void *han;
+\&     size_t sz_int_used;
+\&     void *hdl_int_used;
+\&     char *mount_path = "/mnt/";
+\&     char *file = "file_to_open";
+\&     if (path_to_handle(file, &han, &hlen) < 0) {
+\&             perror("path-to-handle");
+\&             exit(1);
+\&     }
+\&     /*
+\&      * path_to_fshandle saves an internal copy of the mount point's
+\&      * (/mnt in this example) file descriptor. The open_by_handle call
+\&      * looks up this internal file descriptor and uses it in the
+\&      * xfsctl call to the kernel. Once path_to_fshandle is called,
+\&      * this internal file descriptor remains open for the remaining
+\&      * life of the application.
+\&      */
+\&     path_to_fshandle(mount_path, &hdl_int_used, &sz_int_used);
+\&     fd = open_by_handle(han, hlen, O_RDWR);
 .BR open (2),
 .BR readlink (2),

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