[apple/xnu.git] / bsd / man / man2 / getfh.2

.\"
.\" Copyright (c) 2002-2007 Apple Inc.  All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\" 
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this
.\" file.
.\" 
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\" 
.\" @APPLE_LICENSE_HEADER_END@
.\"
.\"	$NetBSD: getfh.2,v 1.7 1995/10/12 15:40:53 jtc Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University 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 REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
.\"
.\"	@(#)getfh.2	8.1 (Berkeley) 6/9/93
.\"
.Dd January 9, 2007
.Dt GETFH 2
.Os
.Sh NAME
.Nm getfh
.Nd get file handle
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/mount.h>
.Ft int
.Fn getfh "const char *path" "fhandle_t *fhp"
.Sh DESCRIPTION
.Fn getfh
returns a file handle for the specified file or directory
in the file handle pointed to by
.Fa fhp .
This system call is restricted to the super-user and is used by an
NFS server's
.Xr nfsd 8
daemon to obtain file handles used in NFS MOUNT service replies.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.  Otherwise, -1
is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn getfh
fails if one or more of the following are true:
.Bl -tag -width Er
.It Bq ENOTDIR
A component of the path prefix of
.Fa path
is not a directory.
.It Bq ENAMETOOLONG
The length of a component of
.Fa path
exceeds
.Dv {NAME_MAX}
characters, or the length of
.Fa path
exceeds
.Dv {PATH_MAX}
characters.
.It Bq ENOENT
The file referred to by
.Fa path
does not exist.
.It Bq EPERM
The caller is not the super-user.
.It Bq EACCES
Search permission is denied for a component of the path prefix of
.Fa path .
.It Bq ELOOP
Too many symbolic links were encountered in translating
.Fa path .
.It Bq EFAULT
.Fa Fhp
points to an invalid address.
.It Bq EIO
An
.Tn I/O
error occurred while reading from or writing to the file system.
.El
.Sh SEE ALSO
.Xr nfsd 8
.Sh HISTORY
The
.Fn getfh
function first appeared in 4.4BSD.
Commit	Line	Data
2d21ac55 A	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	.\"
9bccf70c A	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	.\"
2d21ac55	58	.Dd January 9, 2007
9bccf70c A	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
39037602	70	.Fn getfh
9bccf70c A	71	returns a file handle for the specified file or directory
	72	in the file handle pointed to by
	73	.Fa fhp .
2d21ac55 A	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.
9bccf70c	78	.Sh RETURN VALUES
2d21ac55 A	79	Upon successful completion, a value of 0 is returned. Otherwise, -1
2d21ac55 A	80	is returned and the global variable
9bccf70c A	81	.Va errno
	82	is set to indicate the error.
	83	.Sh ERRORS
39037602	84	.Fn getfh
9bccf70c A	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
2d21ac55	94	exceeds
9bccf70c A	95	.Dv {NAME_MAX}
	96	characters, or the length of
	97	.Fa path
2d21ac55 A	98	exceeds
2d21ac55 A	99	.Dv {PATH_MAX}
9bccf70c A	100	characters.
	101	.It Bq ENOENT
	102	The file referred to by
	103	.Fa path
	104	does not exist.
2d21ac55 A	105	.It Bq EPERM
2d21ac55 A	106	The caller is not the super-user.
9bccf70c A	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
2d21ac55 A	121	.Sh SEE ALSO
2d21ac55 A	122	.Xr nfsd 8
9bccf70c A	123	.Sh HISTORY
	124	The
	125	.Fn getfh
2d21ac55	126	function first appeared in 4.4BSD.