HANDLE(3)							     HANDLE(3)

NAME    [Toc]    [Back]

     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 - file	handle
     operations

C SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <sys/handle.h>

     int path_to_handle	(char *path, void **hanp, size_t *hlen);

     int path_to_fshandle (char	*path, void **hanp, size_t *hlen);

     int fd_to_handle (int fd, void **hanp, size_t *hlen);

     int handle_to_fshandle (void *hanp, size_t	hlen, void **fshanp, size_t *fshlen);

     int open_by_handle	(void *hanp, size_t hlen, int oflag);

     int readlink_by_handle (void *hanp, size_t	hlen, void *buf, size_t	bs);

     int attr_multi_by_handle (void *hanp, size_t hlen,	void *buf,
					   int rtrvcnt,	int flags);

     int attr_list_by_handle (void *hanp, size_t hlen, char *buf, size_t bufsiz,
					  int flags, struct attrlist_cursor *cursor);

     int fssetdm_by_handle (void *hanp,	size_t hlen, struct fsdmidata *fssetdm);

     void free_handle (void *hanp, size_t hlen);

DESCRIPTION    [Toc]    [Back]

     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.	Device
     management	capabilities or	root privileges	are required to	use
     open_by_handle() readlink_by_handle(), attr_multi_by_handle(),
     attr_list_by_handle(), and	fssetdm_by_handle().  Link with	the -ldm
     library to	access these functions.

     A 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.




									Page 1






HANDLE(3)							     HANDLE(3)



     The path_to_handle() function returns the handle for the object given by
     the path argument.	 If the	final component	of the path name is a symbolic
     link, the handle returned is that of the link itself.

     The path_to_fshandle() function returns the handle	for the	filesystem in
     which the object given by the path	argument resides.

     The fd_to_handle()	function returns the handle for	the object referenced
     by	the fd argument, which must be a valid file descriptor.

     The handle_to_fshandle() function returns the handle for the filesystem
     in	which the object referenced by the handle given	by the hanp and	hlen
     arguments resides.

     The open_by_handle() function opens a file	descriptor for the object
     referenced	by a handle.  It is analogous and identical to open(2) with
     the exception of accepting	handles	instead	of path	names.

     The readlink_by_handle() function returns the contents of a symbolic link
     referenced	by a handle.

     The attr_multi_by_handle()	function manipulates multiple user attributes
     on	a filesystem object.  It is analogous and identical to attr_multif(2)
     except that a handle is specified instead of a file descriptor.

     The attr_list_by_handle() function	returns	the names of the user
     attributes	of a filesystem	object.	 It is analogous and identical to
     attr_listf(2) except that a handle	is specified instead of	a file
     descriptor.

     The fssetdm_by_handle() function sets the di_dmevmask and di_dmstate
     fields in an XFS on-disk inode.  It is analogous to the F_FSSETDM
     subfunction of fcntl(2) except that a handle is specified instead of a
     file descriptor.

     The free_handle() function	frees the storage allocated for	handles
     returned by the following functions:  path_to_handle(),
     path_to_fshandle(), fd_to_handle(), and handle_to_fshandle().

     In	IRIX releases prior to 6.5 the declarations for	these functions	were
     obtained by including <sys/fs/xfs_handle.h> instead of <sys/handle.h>.

SEE ALSO    [Toc]    [Back]

     open(2), readlink(2), attr_multi(2), attr_list(2),	fcntl(2).

DIAGNOSTICS    [Toc]    [Back]

     The function free_handle()	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 errno to indicate the error:






									Page 2






HANDLE(3)							     HANDLE(3)



     [EACCES]	    Search permission was denied for a component of path.

     [EBADF]	    fd is not a	valid and open file descriptor.

     [EFAULT]	    An argument	pointed	to an invalid address.

     [EINVAL]	    path is in a filesystem that does not support these
		    functions.

     [ELOOP]	    Too	many symbolic links were encountered in	translating
		    the	path name.

     [ENAMETOOLONG] A component	of path	or the entire length of	path exceeds
		    filesystem limits.

     [ENOENT]	    A component	of path	does not exist.

     [EPERM]	    The	caller does not	have sufficient	privileges.


									PPPPaaaaggggeeee 3333