bsd/man/man2/fsctl.2

   1 .\"
   2 .\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5 .\"
   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 .\"
  20 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  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.