Document fhopen, fhstat, and fhstatfs syscalls.

Obtained from:	NetBSD

1 files changed, 134 insertions, 0 deletions

diff --git a/lib/libc/sys/fhopen.2 b/lib/libc/sys/fhopen.2
new file mode 100644
index 0000000..4c306a6
--- /dev/null
+++ b/lib/libc/sys/fhopen.2
@@ -0,0 +1,134 @@
+.\"	$NetBSD: fhopen.2,v 1.1 1999/06/30 01:32:15 wrstuden Exp $
+.\"	$FreeBSD$
+.\"
+.\" Copyright (c) 1999 National Aeronautics & Space Administration
+.\" All rights reserved.
+.\"
+.\" This software was written by William Studenmund of the
+.\" Numerical Aerospace Similation Facility, NASA Ames Research Center.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the the name of the National Aeronautics & Space Administration
+.\"    nor the names of its contributors may be used to endorse or promote
+.\"    products derived from this software without specific prior written
+.\"    permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NATIONAL AERONAUTICS & SPACE ADMINISTRATION
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ADMINISTRATION OR CONTRIB-
+.\" UTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"/
+.Dd June 29, 1999
+.Dt FHOPEN 2
+.Os
+.Sh NAME
+.Nm fhopen ,
+.Nm fhstat ,
+.Nm fhstatfs
+.Nd access file via file handle
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/stat.h>
+.Fd #include <sys/mount.h>
+.Ft int
+.Fn fhopen "const fhandle_t *fhp" "int flags"
+.Ft int
+.Fn fhstat "const fhandle_t *fhp" "struct stat *sb"
+.Ft int
+.Fn fhstatfs "const fhandle_t *fhp" "struct statfs *buf"
+.Sh DESCRIPTION
+These functions provide a means to access a file given the file handle
+.Fa fhp.
+As this method bypasses directory access restrictions, these calls are
+restricted to the superuser.
+.Pp
+.Fn fhopen
+opens the file referenced by
+.Fa fhp
+for reading and/or writing as specified by the argument
+.Fa flags
+and returns the file descriptor to the calling process. The
+.Fa flags
+are specified by
+.Em or Ns 'ing
+together the flags used for the
+.Xr open 2
+call. All said flags are valid except for
+.Dv O_CREAT .
+.Pp
+.Fn fhstat
+and
+.Fn fhstatfs
+provide the functionality of the
+.Xr fstat 2
+and
+.Xr fstatfs 2
+calls except that they return information for the file refered to by
+.Fa fhp
+rather than an open file.
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn fhopen
+returns the file descriptor for the opened file, while
+.Fn fhstat
+and
+.Fn fhstatfs
+return 0.
+Otherwise, -1 is returned and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+In addition to the errors returned by
+.Xr open 2 ,
+.Xr fstat 2 ,
+and
+.Xr fstatfs 2
+respectivly,
+.Fn fhopen ,
+.Fn fhstat ,
+and
+.Fn fhstatfs
+will return
+.Bl -tag -width Er
+.It Bq Er EINVAL
+Calling
+.Fn fhopen
+with
+.Dv O_CREAT
+set.
+.It Bq Er ESTALE
+The file handle
+.Fa fhp
+is no longer valid.
+.El
+.Sh SEE ALSO
+.Xr getfh 2 ,
+.Xr open 2 ,
+.Xr fstat 2 ,
+.Xr fstatfs 2
+.Sh HISTORY
+The
+.Fn fhopen ,
+.Fn fhstat ,
+and
+.Fn fhstatfs
+functions first appeared in
+.Nx 1.5 .
+.Sh AUTHORS
+This man page was written by
+.An William Studenmund
+for NetBSD.