lib/libautofs/libautofs.3

   1 .\" Copyright (c) 2004 Alfred Perlstein <alfred@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $Id: libautofs.3,v 1.4 2004/09/08 08:12:21 bright Exp $
  26 .\" $FreeBSD$
  27 .Dd September 9, 2004
  28 .Dt LIBAUTOFS 3
  29 .Os
  30 .Sh NAME
  31 .Nm libautofs
  32 .Nd "procedural interface to managing an autofs file system"
  33 .Sh SYNOPSIS
  34 .In libautofs.h
  35 .Ft int
  36 .Fn autoh_get "const char *path" "autoh_t *hndlp"
  37 .Ft void
  38 .Fn autoh_free "autoh_t hndl"
  39 .Ft int
  40 .Fn autoh_getall "autoh_t **hndlpp" "int *cnt"
  41 .Ft void
  42 .Fn autoh_freeall "autoh_t *hndlep"
  43 .Ft int
  44 .Fn autoh_fd "autoh_t hndl"
  45 .Ft const char *
  46 .Fn autoh_mp "autoh_t hndl"
  47 .Ft int
  48 .Fn autoreq_get "autoh_t hndl" "autoreq_t **reqpp" "int *cntp"
  49 .Ft void
  50 .Fn autoreq_free "autoh_t hndl" "autoreq_t *reqp"
  51 .Ft int
  52 .Fn autoreq_serv "autoh_t hndl" "autoreq_t req"
  53 .Ft enum autoreq_op
  54 .Fn autoreq_getop "autoreq_t req"
  55 .Ft const char *
  56 .Fn autoreq_getpath "autoreq_t req"
  57 .Ft autoino_t
  58 .Fn autoreq_getino "autoreq_t req"
  59 .Ft autoino_t
  60 .Fn autoreq_getdirino "autoreq_t req"
  61 .Ft void
  62 .Fn autoreq_getaux "autoreq_t req" "void **auxdatap" "size_t *auxsizep"
  63 .Ft void
  64 .Fn autoreq_getoffset "autoreq_t req" "off_t *offp"
  65 .Ft void
  66 .Fn autoreq_getxid "autoreq_t req" "int *xidp"
  67 .Ft void
  68 .Fn autoreq_setino "autoreq_t req" "autoino_t ino"
  69 .Ft void
  70 .Fn autoreq_seterrno "autoreq_t req" "int errno"
  71 .Ft void
  72 .Fn autoreq_setaux "autoreq_t req" "void *auxdata" "size_t auxsize"
  73 .Ft void
  74 .Fn autoreq_seteof "autoreq_t req" "int eof"
  75 .Ft int
  76 .Fn autoh_togglepath "autoh_t hndl" "int toggle" "pid_t pid" "const char *path"
  77 .Ft int
  78 .Fn autoh_togglefd "autoh_t hndl" "int toggle" "pid_t pid" "int fd"
  79 .Sh DESCRIPTION
  80 The
  81 .Nm libautofs
  82 library provides a "mostly" stable interface to the
  83 .Xr autofs 9
  84 file system.
  85 .Pp
  86 The interface to
  87 .Xr autofs 9
  88 is managed via handles of type
  89 .Fa autoh_t
  90 and
  91 .Fa autoreq_t
  92 which refer to handles to
  93 .Xr autofs 9
  94 mount points and requests respectively.
  95 .Pp
  96 The
  97 .Fn autoh_get
  98 function returns a handle to an
  99 .Xr autofs 9
 100 file system based on the
 101 .Fa path
 102 parameter.
 103 The handle returned should be freed via the
 104 .Fn autoh_free
 105 function.
 106 .Pp
 107 The
 108 .Fn autoh_getall
 109 function returns an array of handles to all mounted
 110 .Xr autofs 9
 111 file systems, each of which should be released via the
 112 .Fn autoh_free
 113 function or released en-mass via the
 114 .Fn autoh_freeall
 115 function.
 116 .Pp
 117 The
 118 .Fn autoh_fd
 119 function returns a file descriptor that can be used with
 120 .Xr select 2
 121 or
 122 .Xr poll 2
 123 to check for "exceptional" data to detect an
 124 .Xr autofs 9
 125 event.
 126 Users of
 127 .Xr select 2
 128 should set the fd in the
 129 .Fa exceptfds
 130 fd_set.
 131 Users of
 132 .Xr poll 2
 133 should set POLLPRI in the pollfd
 134 .Fa fds
 135 argument.
 136 .Pp
 137 The
 138 .Fn autoh_mp
 139 function returns the path to the autofs file system that the
 140 .Fa hndl
 141 is derived from.
 142 .Pp
 143 The
 144 .Fn autoreq_get
 145 function returns an array of autofs requests in
 146 .Fa reqpp ,
 147 the number of requests is stored into
 148 .Fa cntp .
 149 Each request should be released using the
 150 .Fn autoreq_free
 151 function.
 152 .Pp
 153 Requests that are retrieved via the
 154 .Fn autoreq_get
 155 are served via the "autoreq_" functions.
 156 .Pp
 157 The following functions returns information about the request.
 158 .Bl -tag -width indent
 159 .It Fn autoreq_getop
 160 return the operation type of the request, that would be one of
 161 AUTOREQ_OP_UNKNOWN, AUTOREQ_OP_LOOKUP, AUTOREQ_OP_STAT, AUTOREQ_OP_READDIR
 162 depending on the type of request that
 163 .Xr autofs 9
 164 requires service from.
 165 .It Fn autoreq_getpath
 166 return the path of the mountpoint associated with the request
 167 .Fa req .
 168 .It Fn autoreq_getino
 169 return the inode associated with the request
 170 .Fa req .
 171 .It Fn autoreq_getdirno
 172 return the directory inode associated with the request
 173 .Fa req .
 174 .It Fn autoreq_getaux
 175 return the auxiliary data associated with the request
 176 .Fa req .
 177 .It Fn autoreq_getoffset
 178 return the offset request associated with the request
 179 .Fa req .
 180 (used for readdir request)
 181 .It Fn autoreq_getxid
 182 return the transaction id associated with an autofs request, these
 183 are unique per mount point, but not system wide.
 184 They can be used
 185 for debugging to ensure requests are being accepted by the kernel.
 186 .El
 187 .Pp
 188 The following functions allow one to set the response sent to
 189 .Xr autofs 9
 190 to the requesting userland application.
 191 .Bl -tag -width indent
 192 .It Fn autoreq_setino
 193 Set the request
 194 .Fa req
 195 inode to
 196 .Fa ino ,
 197 this is typically unused.
 198 .It Fn autoreq_seterrno
 199 set the error returned to the application sending the request, typically
 200 this is left alone, or set to ENOENT if the request is for a non-existent
 201 name.
 202 The default error is no error.
 203 Meaning the application will see
 204 a successful return.
 205 .It Fn autoreq_setaux
 206 used to set the auxiliary data for a request, currently used to set
 207 the dirent structures for serving a readdir request.
 208 Default is no
 209 auxiliary data.
 210 .It Fn autoreq_seteof
 211 used to set the eof flag for readdir requests (default is not eof.)
 212 .El
 213 .Pp
 214 The functions
 215 .Fn autoh_togglepath
 216 and
 217 .Fn autoh_togglefd
 218 are used to set options on an
 219 .Xr autofs 9
 220 directory via
 221 .Fa path
 222 and
 223 .Fa fd
 224 respectively.
 225 The
 226 .Fa pid
 227 argument should be set to the pid of the process serving
 228 .Xr autofs 9
 229 requests, or -1 to disable the option.
 230 The options are
 231 .Bl -tag -width AUTO_INDIRECT
 232 .It Fa AUTO_MOUNTER
 233 set this process as the one responsible for the
 234 .Xr autofs 9
 235 node, if this process exits, then requests into the autofs will begin to fail.
 236 .It Fa AUTO_BROWSE
 237 dispatch directory read requests for this node to the process identified by
 238 .Fa pid .
 239 Specifically, calls to
 240 .Xr getdirentries 2
 241 and
 242 .Xr getdents 2
 243 will be routed to userland after the current actual directory contents
 244 are read into userland.
 245 .It Fa AUTO_DIRECT
 246 Set the directory as a mount trigger.
 247 Any request to enter the directory
 248 will trigger a callback into the process
 249 .Fa pid .
 250 .It Fa AUTO_INDIRECT
 251 Set the directory as an indirect trigger.
 252 Any request for an entry inside
 253 the directory will be routed to the process identified by
 254 .Fa pid .
 255 .El
 256 .Sh EXAMPLES
 257 See /usr/share/examples/autofs/driver/
 258 .Sh HISTORY
 259 The
 260 .Nm
 261 utility first appeared in
 262 .Fx 6.0 .
 263 .Sh AUTHORS
 264 This manual page and the autofs file system suite were written by
 265 .An Alfred Perlstein .