bsd/man/man2/fsctl.2

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