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

.\"
.\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\" 
.\" The contents of this file constitute Original Code as defined in and
.\" are subject to the Apple Public Source License Version 1.1 (the
.\" "License").  You may not use this file except in compliance with the
.\" License.  Please obtain a copy of the License at
.\" http://www.apple.com/publicsource and read it before using this file.
.\" 
.\" This 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 OR NON-INFRINGEMENT.  Please see the
.\" License for the specific language governing rights and limitations
.\" under the License.
.\" 
.\" @APPLE_LICENSE_HEADER_END@
.\"
.Dd January 14, 2003
.Dt FSCTL 2
.Os "Mac OS X"
.Sh NAME
.Nm fsctl
.Nd control filesystems
.Sh SYNOPSIS
.Fd #include <sys/attr.h>
.Fd #include <sys/ioctl.h>
.Ft int
.Fn fsctl "const char *path" "unsigned long request" "void *data" "unsigned long options"
.Sh DESCRIPTION
The
.Fn fsctl
function manipulates the filesystem controlling mounted volumes.
In particular, many filesystem-specific operating
characteristics of mounted filesystems may be controlled
with
.Fn fsctl
requests.
.Fn fsctl
requests can also be used to extract filesystem-specific
information for a mounted volumes.
.Pp
.Fa path
is the path name of any file within the mounted filesystem.
An  fsctl
.Fa request
has encoded in it whether the argument is an
.Dq in
parameter
or
.Dq out
parameter, and the size of the argument
.Fa data
in bytes.
Values for
.Fa request
are entirely filesystem-specific except for the following, defined in
.Ao Pa sys/fsctl.h Ac :
.Bd -literal  -offset indent
FSGETMOUNTINFOSIZE	/* Return size of mount info data */
.Ed
.Pp
Macros and defines used in specifying an fsctl
.Fa request
are the same as for
.Fn ioctl
requests and are located in the file
.Ao Pa sys/ioccom.h Ac .
.Fa options
may specify special flags for the processing of the
.Fn fsctl
call.  The options are specified by
.Em or Ns 'ing
the option values.  The only option currently defined is
.Bd -literal -offset indent
#define FSOPT_NOFOLLOW	0x00000001	/* Don't follow symlinks */
.Ed
.Pp
which is interpreted by the
.Fn fsctl
call to prevent following of symlinks.  The
.Fa options
argument is passed to the filesystem, which may define and handle
additional
.Fa options
bit values.
.Sh RETURN VALUES
.Pp
If an error has occurred, a value of -1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn fsctl
will fail if:
.Bl -tag -width Er
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 
.Dv {NAME_MAX}
characters, or an entire path name exceeded 
.Dv {PATH_MAX}
characters.
.It Bq Er ENOENT
The named file does not exist.
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.It Bq Er EFAULT
.Fa path
or
.Em data
points to an invalid address.
.It Bq Er EIO
An
.Tn I/O
error occurred while reading from or writing to the file system.
.It Bq Er EINVAL
.Fa request
or
.Fa data
is not valid.
.El
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr getattrlist 2 ,
.Xr setattrlist 2
.Sh HISTORY
The
.Fn fsctl
function call appeared in Mac OS X version 10.0.
Commit	Line	Data
55e303ae A	1	.\"
	2	.\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
	3	.\"
6601e61a	4	.\" @APPLE_LICENSE_HEADER_START@
55e303ae	5	.\"
8f6c56a5 A	6	.\" The contents of this file constitute Original Code as defined in and
	7	.\" are subject to the Apple Public Source License Version 1.1 (the
	8	.\" "License"). You may not use this file except in compliance with the
	9	.\" License. Please obtain a copy of the License at
	10	.\" http://www.apple.com/publicsource and read it before using this file.
	11	.\"
	12	.\" This Original Code and all software distributed under the License are
	13	.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	14	.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	15	.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	16	.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	17	.\" License for the specific language governing rights and limitations
	18	.\" under the License.
	19	.\"
6601e61a	20	.\" @APPLE_LICENSE_HEADER_END@
55e303ae A	21	.\"
	22	.Dd January 14, 2003
	23	.Dt FSCTL 2
	24	.Os "Mac OS X"
	25	.Sh NAME
	26	.Nm fsctl
	27	.Nd control filesystems
	28	.Sh SYNOPSIS
	29	.Fd #include <sys/attr.h>
	30	.Fd #include <sys/ioctl.h>
	31	.Ft int
	32	.Fn fsctl "const char path" "unsigned long request" "void data" "unsigned long options"
	33	.Sh DESCRIPTION
	34	The
	35	.Fn fsctl
	36	function manipulates the filesystem controlling mounted volumes.
	37	In particular, many filesystem-specific operating
	38	characteristics of mounted filesystems may be controlled
	39	with
	40	.Fn fsctl
	41	requests.
	42	.Fn fsctl
	43	requests can also be used to extract filesystem-specific
	44	information for a mounted volumes.
	45	.Pp
	46	.Fa path
	47	is the path name of any file within the mounted filesystem.
	48	An fsctl
	49	.Fa request
	50	has encoded in it whether the argument is an
	51	.Dq in
	52	parameter
	53	or
	54	.Dq out
	55	parameter, and the size of the argument
	56	.Fa data
	57	in bytes.
	58	Values for
	59	.Fa request
	60	are entirely filesystem-specific except for the following, defined in
	61	.Ao Pa sys/fsctl.h Ac :
	62	.Bd -literal -offset indent
	63	FSGETMOUNTINFOSIZE /* Return size of mount info data */
	64	.Ed
	65	.Pp
	66	Macros and defines used in specifying an fsctl
	67	.Fa request
	68	are the same as for
	69	.Fn ioctl
	70	requests and are located in the file
	71	.Ao Pa sys/ioccom.h Ac .
	72	.Fa options
	73	may specify special flags for the processing of the
	74	.Fn fsctl
	75	call. The options are specified by
	76	.Em or Ns 'ing
	77	the option values. The only option currently defined is
	78	.Bd -literal -offset indent
	79	#define FSOPT_NOFOLLOW 0x00000001 /* Don't follow symlinks */
	80	.Ed
	81	.Pp
	82	which is interpreted by the
	83	.Fn fsctl
	84	call to prevent following of symlinks. The
85	.Fa options
86	argument is passed to the filesystem, which may define and handle
87	additional
88	.Fa options
89	bit values.
90	.Sh RETURN VALUES
91	.Pp
92	If an error has occurred, a value of -1 is returned and
93	.Va errno
94	is set to indicate the error.
95	.Sh ERRORS
96	.Fn fsctl
97	will fail if:
98	.Bl -tag -width Er
99	.It Bq Er ENOTDIR
100	A component of the path prefix is not a directory.
101	.It Bq Er ENAMETOOLONG
102	A component of a pathname exceeded
103	.Dv {NAME_MAX}
104	characters, or an entire path name exceeded
105	.Dv {PATH_MAX}
106	characters.
107	.It Bq Er ENOENT
108	The named file does not exist.
109	.It Bq Er EACCES
110	Search permission is denied for a component of the path prefix.
111	.It Bq Er ELOOP
112	Too many symbolic links were encountered in translating the pathname.
113	.It Bq Er EFAULT
114	.Fa path
115	or
116	.Em data
117	points to an invalid address.
118	.It Bq Er EIO
119	An
120	.Tn I/O
121	error occurred while reading from or writing to the file system.
122	.It Bq Er EINVAL
123	.Fa request
124	or
125	.Fa data
126	is not valid.
127	.El
128	.Sh SEE ALSO
129	.Xr ioctl 2 ,
130	.Xr getattrlist 2 ,
131	.Xr setattrlist 2
132	.Sh HISTORY
133	The
134	.Fn fsctl
135	function call appeared in Mac OS X version 10.0.