lib/libc/sys/fhopen.2

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