name_to_handle_at man page on SuSE

Man page or keyword search:  
man Server   14857 pages
apropos Keyword Search (all sections)
Output format
SuSE logo
[printable version]

OPEN_BY_HANDLE_AT(2)	   Linux Programmer's Manual	  OPEN_BY_HANDLE_AT(2)

NAME
       name_to_handle_at - generate a file handle from a pathname
       open_by_handle_at - open a file using a file handle

SYNOPSIS
       int name_to_handle_at(int dfd, const char * name,
			     struct file_handle handle, int * mnt_id,
			     int flag);

       int open_by_handle_at(int mountdirfd, struct file_handle handle,
			     int flags);

DESCRIPTION
       open_by_handle_at() opens the file referenced by the file handle speci‐
       fied with handle.  This system  call  uses  the	file  handle  that  is
       returned	 by the name_to_handle_at() system call. Both system calls can
       be considered to split the behavior of the open() system call.

       The struct file_handle is defined with the following data structure:

	   struct file_handle {
		unsigned int handle_bytes; /* size of the file handle f_handle */
		int handle_type;	   /* type of the file handle */
		void *f_handle;		   /* file handle */
	   };

       The size of the file handle data structure is specified in handle_bytes
       as the actual file handle can have a varying size. The variable of han‐
       dle_type specifies how the file within the filesystem is encoded.  This
       value is set to one of the following values:

	   enum fid_type {
		   /*
		    * The root, or export point, of the filesystem.
		    * (Never actually passed down to the filesystem.
		    */
		   FILEID_ROOT = 0,

		   /*
		    * 32bit inode number, 32 bit generation number.
		    */
		   FILEID_INO32_GEN = 1,

		   /*
		    * 32bit inode number, 32 bit generation number,
		    * 32 bit parent directory inode number.
		    */
		   FILEID_INO32_GEN_PARENT = 2,

		   /*
		    * 64 bit object ID, 64 bit root object ID,
		    * 32 bit generation number.
		    */
		   FILEID_BTRFS_WITHOUT_PARENT = 0x4d,

		   /*
		    * 64 bit object ID, 64 bit root object ID,
		    * 32 bit generation number,
		    * 64 bit parent object ID, 32 bit parent generation.
		    */
		   FILEID_BTRFS_WITH_PARENT = 0x4e,
		   /*
		    * 64 bit object ID, 64 bit root object ID,
		    * 32 bit generation number,
		    * 64 bit parent object ID, 32 bit parent generation,
		    * 64 bit parent root object ID.
		    */
		   FILEID_BTRFS_WITH_PARENT_ROOT = 0x4f,

		   /*
		    * 32 bit block number, 16 bit partition reference,
		    * 16 bit unused, 32 bit generation number.
		    */
		   FILEID_UDF_WITHOUT_PARENT = 0x51,

		   /*
		    * 32 bit block number, 16 bit partition reference,
		    * 16 bit unused, 32 bit generation number,
		    * 32 bit parent block number, 32 bit parent generation number
		    */
		   FILEID_UDF_WITH_PARENT = 0x52,

		   /*
		    * 64 bit checkpoint number, 64 bit inode number,
		    * 32 bit generation number.
		    */
		   FILEID_NILFS_WITHOUT_PARENT = 0x61,

		   /*
		    * 64 bit checkpoint number, 64 bit inode number,
		    * 32 bit generation number, 32 bit parent generation.
		    * 64 bit parent inode number.
		    */
		   FILEID_NILFS_WITH_PARENT = 0x62,
	   };

       The  actual file handle held in the member variable of f_handle must be
       treated as an opaque value by the calling user space  application.  The
       contents	 of  this  handle value may differ depending on the underlying
       file system.

       The  system  call  name_to_handle_at()  performs	 the  lookup  of   the
       requested  file	system	object	and  returns  the  file handle to that
       object. If the pathname given in name is relative, then	it  is	inter‐
       preted relative to the directory referred to by the file descriptor dfd
       (rather than relative to the current working directory  of  the	 call‐
       ing process). When dfd not NULL, the same principle as outlined for the
       openat() system call is applied. Using the parameter handle the calling
       process must specify the maximum size of the file handle. When the ker‐
       nel generated the file handle, handle is filled with  the  file	handle
       type  and  the  actual  file handle. The size of the actual file handle
       provided by the kernel is set in	 handle.handle_bytes.	The  parameter
       mnt_id  is  filled  by  the kernel with the mount id of the file system
       containing the file. The flag parameter allows the calling  process  to
       specify	whether	 to  follow a symlink (using AT_SYMLINK_FOLLOW) or not
       (using AT_EMPTY_PATH).

       The system  call	 open_by_handle_at()  opens  the  file	system	object
       pointed	to  by	the  file  handle handle.  The parameter of mountdirfd
       specifies the file descriptor of the directory used as a base  for  the
       file  system object lookup. The file handle is decoded relative to that
       directory. The flags parameter can be used to  specify  the  same  file
       open flags as documented for the open() system call.

RETURN VALUE
       On  success, open_by_handle_at returns a new file descriptor. On error,
       -1 is returned, and errno is set to indicate the error.

       On success, name_to_handle_at returns 0. On error, -1 is returned,  and
       errno is set to indicate the error.

ERRORS
       open_by_handle_at()  returns  the same errors as documented for open().
       In addition, the following error conditions exist.

       EPERM  The calling process does	not  possess  the  CAP_DAC_READ_SEARCH
	      capability.

       EFAULT The  file	 handle data stucture or the opaque file handle cannot
	      be retrieved by the kernel.

       EINVAL The size of the file handle specified in handle.handle_bytes  is
	      too large.

       ENOMEM The kernel has insufficient memory for performing the operation.

       name_to_handle_at()  returns  the same errors as documented for open().
       In addition, the following error conditions exist.

       EFAULT The file handle data stucture cannot be retrieved by the kernel.

       EINVAL The size of the file handle specified in handle.handle_bytes  is
	      too large.

       ENOMEM The kernel has insufficient memory for performing the operation.

       EINVAL An invalid value was specified in the flag argument.

       EOVERFLOW
	      The  size	 of  the file handle exceeds the size specified by the
	      calling process in handle.handle_bytes.

       EFAULT The kernel is unable to copy the handle data structure  to  user
	      space.

CONFORMING TO
       These  system calls are Linux-specific and appeared in the Linux kernel
       2.6.39.

NOTES
       The system calls, the file handle data structure, as well as  the  file
       handle  types  are  not	yet exported via glibc or another library. The
       system calls must be invoked using the syscall() function.

SEE ALSO
       open(2), openat(2).  syscall(2)

Linux				  2011-09-09		  OPEN_BY_HANDLE_AT(2)
[top]

List of man pages available for SuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net