bsd/man/man2/getfh.2

   1 .\"
   2 .\" Copyright (c) 2002-2007 Apple Inc.  All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. Please obtain a copy of the License at
  10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  11 .\" file.
  12 .\"
  13 .\" The Original Code and all software distributed under the License are
  14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18 .\" Please see the License for the specific language governing rights and
  19 .\" limitations under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .\"     $NetBSD: getfh.2,v 1.7 1995/10/12 15:40:53 jtc Exp $
  24 .\"
  25 .\" Copyright (c) 1989, 1991, 1993
  26 .\"     The Regents of the University of California.  All rights reserved.
  27 .\"
  28 .\" Redistribution and use in source and binary forms, with or without
  29 .\" modification, are permitted provided that the following conditions
  30 .\" are met:
  31 .\" 1. Redistributions of source code must retain the above copyright
  32 .\"    notice, this list of conditions and the following disclaimer.
  33 .\" 2. Redistributions in binary form must reproduce the above copyright
  34 .\"    notice, this list of conditions and the following disclaimer in the
  35 .\"    documentation and/or other materials provided with the distribution.
  36 .\" 3. All advertising materials mentioning features or use of this software
  37 .\"    must display the following acknowledgement:
  38 .\"     This product includes software developed by the University of
  39 .\"     California, Berkeley and its contributors.
  40 .\" 4. Neither the name of the University nor the names of its contributors
  41 .\"    may be used to endorse or promote products derived from this software
  42 .\"    without specific prior written permission.
  43 .\"
  44 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  45 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  46 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  47 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  48 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  49 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  50 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  51 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  52 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  53 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  54 .\" SUCH DAMAGE.
  55 .\"
  56 .\"     @(#)getfh.2     8.1 (Berkeley) 6/9/93
  57 .\"
  58 .Dd January 9, 2007
  59 .Dt GETFH 2
  60 .Os
  61 .Sh NAME
  62 .Nm getfh
  63 .Nd get file handle
  64 .Sh SYNOPSIS
  65 .Fd #include <sys/types.h>
  66 .Fd #include <sys/mount.h>
  67 .Ft int
  68 .Fn getfh "const char *path" "fhandle_t *fhp"
  69 .Sh DESCRIPTION
  70 .Fn Getfh
  71 returns a file handle for the specified file or directory
  72 in the file handle pointed to by
  73 .Fa fhp .
  74 This system call is restricted to the super-user and is used by an
  75 NFS server's
  76 .Xr nfsd 8
  77 daemon to obtain file handles used in NFS MOUNT service replies.
  78 .Sh RETURN VALUES
  79 Upon successful completion, a value of 0 is returned.  Otherwise, -1
  80 is returned and the global variable
  81 .Va errno
  82 is set to indicate the error.
  83 .Sh ERRORS
  84 .Fn Getfh
  85 fails if one or more of the following are true:
  86 .Bl -tag -width Er
  87 .It Bq ENOTDIR
  88 A component of the path prefix of
  89 .Fa path
  90 is not a directory.
  91 .It Bq ENAMETOOLONG
  92 The length of a component of
  93 .Fa path
  94 exceeds
  95 .Dv {NAME_MAX}
  96 characters, or the length of
  97 .Fa path
  98 exceeds
  99 .Dv {PATH_MAX}
 100 characters.
 101 .It Bq ENOENT
 102 The file referred to by
 103 .Fa path
 104 does not exist.
 105 .It Bq EPERM
 106 The caller is not the super-user.
 107 .It Bq EACCES
 108 Search permission is denied for a component of the path prefix of
 109 .Fa path .
 110 .It Bq ELOOP
 111 Too many symbolic links were encountered in translating
 112 .Fa path .
 113 .It Bq EFAULT
 114 .Fa Fhp
 115 points to an invalid address.
 116 .It Bq EIO
 117 An
 118 .Tn I/O
 119 error occurred while reading from or writing to the file system.
 120 .El
 121 .Sh SEE ALSO
 122 .Xr nfsd 8
 123 .Sh HISTORY
 124 The
 125 .Fn getfh
 126 function first appeared in 4.4BSD.