lib/libc/sys/fhopen.2

   1 .\"     $NetBSD: fhopen.2,v 1.1 1999/06/30 01:32:15 wrstuden Exp $
   2 .\"     $FreeBSD: src/lib/libc/sys/fhopen.2,v 1.4.2.7 2002/12/29 16:35:34 schweikh Exp $
   3 .\"
   4 .\" Copyright (c) 1999 National Aeronautics & Space Administration
   5 .\" All rights reserved.
   6 .\"
   7 .\" This software was written by William Studenmund of the
   8 .\" Numerical Aerospace Simulation Facility, NASA Ames Research Center.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the National Aeronautics & Space Administration
  19 .\"    nor the names of its contributors may be used to endorse or promote
  20 .\"    products derived from this software without specific prior written
  21 .\"    permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE NATIONAL AERONAUTICS & SPACE ADMINISTRATION
  24 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  25 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  26 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ADMINISTRATION OR CONTRIB-
  27 .\" UTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  28 .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  29 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  30 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  31 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  32 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33 .\" POSSIBILITY OF SUCH DAMAGE.
  34 .\"/
  35 .Dd June 29, 1999
  36 .Dt FHOPEN 2
  37 .Os
  38 .Sh NAME
  39 .Nm fhopen ,
  40 .Nm fhstat ,
  41 .Nm fhstatfs
  42 .Nd access file via file handle
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In sys/param.h
  47 .In sys/mount.h
  48 .In sys/stat.h
  49 .Ft int
  50 .Fn fhopen "const fhandle_t *fhp" "int flags"
  51 .Ft int
  52 .Fn fhstat "const fhandle_t *fhp" "struct stat *sb"
  53 .Ft int
  54 .Fn fhstatfs "const fhandle_t *fhp" "struct statfs *buf"
  55 .Sh DESCRIPTION
  56 These functions provide a means to access a file given the file handle
  57 .Fa fhp .
  58 As this method bypasses directory access restrictions, these calls are
  59 restricted to the superuser.
  60 .Pp
  61 .Fn fhopen
  62 opens the file referenced by
  63 .Fa fhp
  64 for reading and/or writing as specified by the argument
  65 .Fa flags
  66 and returns the file descriptor to the calling process.
  67 The
  68 .Fa flags
  69 are specified by
  70 .Em or Ns 'ing
  71 together the flags used for the
  72 .Xr open 2
  73 call.
  74 All said flags are valid except for
  75 .Dv O_CREAT .
  76 .Pp
  77 .Fn fhstat
  78 and
  79 .Fn fhstatfs
  80 provide the functionality of the
  81 .Xr fstat 2
  82 and
  83 .Xr fstatfs 2
  84 calls except that they return information for the file referred to by
  85 .Fa fhp
  86 rather than an open file.
  87 .Sh RETURN VALUES
  88 Upon successful completion,
  89 .Fn fhopen
  90 returns the file descriptor for the opened file;
  91 otherwise the value \-1 is returned and the global variable
  92 .Va errno
  93 is set to indicate the error.
  94 .Pp
  95 .Rv -std fhstat fhstatfs
  96 .Sh ERRORS
  97 In addition to the errors returned by
  98 .Xr open 2 ,
  99 .Xr fstat 2 ,
 100 and
 101 .Xr fstatfs 2
 102 respectively,
 103 .Fn fhopen ,
 104 .Fn fhstat ,
 105 and
 106 .Fn fhstatfs
 107 will return
 108 .Bl -tag -width Er
 109 .It Bq Er EINVAL
 110 Calling
 111 .Fn fhopen
 112 with
 113 .Dv O_CREAT
 114 set.
 115 .It Bq Er ESTALE
 116 The file handle
 117 .Fa fhp
 118 is no longer valid.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr fstat 2 ,
 122 .Xr fstatfs 2 ,
 123 .Xr getfh 2 ,
 124 .Xr open 2
 125 .Sh HISTORY
 126 The
 127 .Fn fhopen ,
 128 .Fn fhstat ,
 129 and
 130 .Fn fhstatfs
 131 functions first appeared in
 132 .Nx 1.5
 133 and was adapted to
 134 .Fx 4.0
 135 by Alfred Perlstein.
 136 .Sh AUTHORS
 137 This man page was written by
 138 .An William Studenmund
 139 for
 140 .Nx .