Return to handle.3 CVS log

Up to [Development] / xfs-cmds / xfsprogs / man / man3

Parent pointer userspace support. Adds in libhandle code and xfs_io parent command support.
Merge of master-melb:xfs-cmds:24394a by kenmcd.

  Add the getparents handle functions.

.TH HANDLE 3 
.SH NAME
path_to_handle, path_to_fshandle, fd_to_handle, handle_to_fshandle, open_by_handle, readlink_by_handle, attr_multi_by_handle, attr_list_by_handle, fssetdm_by_handle, free_handle, getparents_by_handle, getparentpaths_by_handle \- file handle operations
.SH C SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <xfs/handle.h>
.PP
.B "int path_to_handle (char *path, void **hanp,"
.B "                    size_t *hlen);"
.PP
.B "int path_to_fshandle (char *path, void **hanp,"
.B "                      size_t *hlen);"
.PP
.B "int fd_to_handle (int fd, void **hanp, size_t *hlen);
.PP
.B "int handle_to_fshandle (void *hanp, size_t hlen,"
.B "                        void **fshanp, size_t *fshlen);
.PP
.B "int open_by_handle (void *hanp, size_t hlen,"
.B "                    int oflag);"
.PP
.B "int readlink_by_handle (void *hanp, size_t hlen,"
.B "                        void *buf, size_t bs);
.PP
.B "int attr_multi_by_handle (void *hanp, size_t hlen,"
.B "                          void *buf, int rtrvcnt,"
.B "                          int flags);"
.PP
.B "int attr_list_by_handle (void *hanp, size_t hlen,"
.B "                         char *buf, size_t bufsiz,"
.B "                         int flags,"
.B "                         struct attrlist_cursor *cursor);"
.PP
.B "int fssetdm_by_handle (void *hanp, size_t hlen,"
.B "                       struct fsdmidata *fssetdm);"
.PP
.B "void free_handle (void *hanp, size_t hlen);
.PP
.B "int getparents_by_handle(void *hanp, size_t hlen,"
.B "                         parent_t *buf, size_t bufsiz,"
.B "                         parent_cursor_t *cursor,"
.B "                         unsigned int *count, unsigned int *more);"
.PP
.B "int getparentpaths_by_handle(void *hanp, size_t hlen,"
.B "                             parent_t *buf, size_t bufsiz,"
.B "                             parent_cursor_t *cursor,"
.B "                             unsigned int *count, unsigned int *more);"
.Op
.SH DESCRIPTION
.PP
These functions provide a way to perform certain
filesystem operations without using a file descriptor
to access filesystem objects.
They are intended for use by a limited set of system utilities
such as backup programs.
They are supported only by the XFS filesystem.
Link with the
.I libhandle
library to access these functions.
.sp
A
.I handle
uniquely identifies a filesystem object
or an entire filesystem.
There is one and only one
handle per filesystem or filesystem object.
Handles consist of some number of bytes.
The size of a handle
(i.e. the number of bytes comprising it)
varies by the type of handle
and may vary for different objects
of the same type.
The content of a handle is opaque to applications.
Since handle sizes vary
and their contents are opaque,
handles are described by two quantities,
a pointer and a size.
The size indicates the number of bytes
in the handle which are pointed to by the pointer.
.P
The \f2path_to_handle\f1() function
returns the handle for the object given by the
.I path
argument.
If the final component of the path name is a symbolic link,
the handle returned is that of the link itself.
.P
The \f2path_to_fshandle\f1() function
returns the handle for the filesystem
in which the object given by the
.I path
argument resides.
.P
The \f2fd_to_handle\f1() function
returns the handle for the object referenced by the
.I fd
argument,
which must be a valid file descriptor.
.P
The \f2handle_to_fshandle\f1() function
returns the handle for the filesystem
in which the object referenced by the
handle given by the
.I hanp
and
.I hlen
arguments resides.
.P
The \f2open_by_handle\f1() function
opens a file descriptor for the object referenced
by a handle.
It is analogous and identical to
.I open(2)
with the exception of accepting handles instead of path names.
.P
The \f2readlink_by_handle\f1() function
returns the contents of a symbolic link
referenced by a handle.
.P
The \f2attr_multi_by_handle\f1() function
manipulates multiple user attributes on a 
filesystem object.
It is analogous and identical to
.I attr_multif(3)
except that a handle is specified instead of a file descriptor.
.P
The \f2attr_list_by_handle\f1() function returns 
the names of the user attributes of a filesystem object.
It is analogous and identical to
.I attr_listf(3)
except that a handle is specified instead of a file descriptor.
.P
The \f2fssetdm_by_handle\f1() function sets the
di_dmevmask and di_dmstate fields in an XFS on-disk inode.
It is analogous to the \f2XFS_IOC_FSSETDM\f1
.I xfsctl(3)
command, except that a handle is specified instead of a file.
.P
The \f2free_handle\f1() function
frees the storage allocated for handles
returned by the following functions:
\f2path_to_handle\f1(),
\f2path_to_fshandle\f1(),
\f2fd_to_handle\f1(),
and
\f2handle_to_fshandle\f1().
.P
The \f2getparents_by_handle\f1() function returns an array
of \f2parent_t\f1 structures for each hardlink to
the inode represented by the given handle. The parent structure
encodes the parent inode number, generation number and the 
basename of the link.
This function is not operational on Linux.
.P
The \f2getparentpaths_by_handle\f1() function is identical to
the \f2getparents_by_handle\f1() function except that instead
of returning the basename it returns the path of the link up
to the mount point.
This function is also not operational on Linux.
.SH "SEE ALSO"
open(2),
readlink(2),
attr_multi(3),
attr_list(3),
xfsctl(3),
xfs(5).
.SH "DIAGNOSTICS"
.PP
The function
\f2free_handle\f1()
has no failure indication.
The other functions
return the value 0 to the calling process
if they succeed;
otherwise, they return the value \-1 and set 
.I errno
to indicate the error:
.sp
.TP 15
.SM
\%[EACCES]
Search permission was denied for a component of
.IR path .
.TP 15
.SM
\%[EBADF]
.I fd
is not a valid and open file descriptor.
.TP 15
.SM
\%[EFAULT]
An argument pointed to an invalid address.
.TP 15
.SM
\%[EINVAL]
.I path
is in a filesystem that does not support these functions.
.TP 15
.SM
\%[ELOOP]
Too many symbolic links were encountered in translating the path name.
.TP 15
.SM
\%[ENAMETOOLONG]
A component of
.I path
or the entire length of
.I path
exceeds filesystem limits.
.TP 15
.SM
\%[ENOENT]
A component of
.I path
does not exist.
.TP 15
.SM
\%[EPERM]
The caller does not have sufficient privileges.