.\" Copyright (c) 2004 Alfred Perlstein .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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. .\" .\" $Id: libautofs.3,v 1.4 2004/09/08 08:12:21 bright Exp $ .\" $FreeBSD$ .Dd September 9, 2004 .Dt LIBAUTOFS 3 .Os .Sh NAME .Nm libautofs .Nd "procedural interface to managing an autofs file system" .Sh SYNOPSIS .In libautofs.h .Ft int .Fn autoh_get "const char *path" "autoh_t *hndlp" .Ft void .Fn autoh_free "autoh_t hndl" .Ft int .Fn autoh_getall "autoh_t **hndlpp" "int *cnt" .Ft void .Fn autoh_freeall "autoh_t *hndlep" .Ft int .Fn autoh_fd "autoh_t hndl" .Ft const char * .Fn autoh_mp "autoh_t hndl" .Ft int .Fn autoreq_get "autoh_t hndl" "autoreq_t **reqpp" "int *cntp" .Ft void .Fn autoreq_free "autoh_t hndl" "autoreq_t *reqp" .Ft int .Fn autoreq_serv "autoh_t hndl" "autoreq_t req" .Ft enum autoreq_op .Fn autoreq_getop "autoreq_t req" .Ft const char * .Fn autoreq_getpath "autoreq_t req" .Ft autoino_t .Fn autoreq_getino "autoreq_t req" .Ft autoino_t .Fn autoreq_getdirino "autoreq_t req" .Ft void .Fn autoreq_getaux "autoreq_t req" "void **auxdatap" "size_t *auxsizep" .Ft void .Fn autoreq_getoffset "autoreq_t req" "off_t *offp" .Ft void .Fn autoreq_getxid "autoreq_t req" "int *xidp" .Ft void .Fn autoreq_setino "autoreq_t req" "autoino_t ino" .Ft void .Fn autoreq_seterrno "autoreq_t req" "int errno" .Ft void .Fn autoreq_setaux "autoreq_t req" "void *auxdata" "size_t auxsize" .Ft void .Fn autoreq_seteof "autoreq_t req" "int eof" .Ft int .Fn autoh_togglepath "autoh_t hndl" "int toggle" "pid_t pid" "const char *path" .Ft int .Fn autoh_togglefd "autoh_t hndl" "int toggle" "pid_t pid" "int fd" .Sh DESCRIPTION The .Nm libautofs library provides a "mostly" stable interface to the .Xr autofs 9 file system. .Pp The interface to .Xr autofs 9 is managed via handles of type .Fa autoh_t and .Fa autoreq_t which refer to handles to .Xr autofs 9 mount points and requests respectively. .Pp The .Fn autoh_get function returns a handle to an .Xr autofs 9 file system based on the .Fa path parameter. The handle returned should be freed via the .Fn autoh_free function. .Pp The .Fn autoh_getall function returns an array of handles to all mounted .Xr autofs 9 file systems, each of which should be released via the .Fn autoh_free function or released en-mass via the .Fn autoh_freeall function. .Pp The .Fn autoh_fd function returns a file descriptor that can be used with .Xr select 2 or .Xr poll 2 to check for "exceptional" data to detect an .Xr autofs 9 event. Users of .Xr select 2 should set the fd in the .Fa exceptfds fd_set. Users of .Xr poll 2 should set POLLPRI in the pollfd .Fa fds argument. .Pp The .Fn autoh_mp function returns the path to the autofs file system that the .Fa hndl is derived from. .Pp The .Fn autoreq_get function returns an array of autofs requests in .Fa reqpp , the number of requests is stored into .Fa cntp . Each request should be released using the .Fn autoreq_free function. .Pp Requests that are retrieved via the .Fn autoreq_get are served via the "autoreq_" functions. .Pp The following functions returns information about the request. .Bl -tag -width indent .It Fn autoreq_getop return the operation type of the request, that would be one of AUTOREQ_OP_UNKNOWN, AUTOREQ_OP_LOOKUP, AUTOREQ_OP_STAT, AUTOREQ_OP_READDIR depending on the type of request that .Xr autofs 9 requires service from. .It Fn autoreq_getpath return the path of the mountpoint associated with the request .Fa req . .It Fn autoreq_getino return the inode associated with the request .Fa req . .It Fn autoreq_getdirno return the directory inode associated with the request .Fa req . .It Fn autoreq_getaux return the auxiliary data associated with the request .Fa req . .It Fn autoreq_getoffset return the offset request associated with the request .Fa req . (used for readdir request) .It Fn autoreq_getxid return the transaction id associated with an autofs request, these are unique per mount point, but not system wide. They can be used for debugging to ensure requests are being accepted by the kernel. .El .Pp The following functions allow one to set the response sent to .Xr autofs 9 to the requesting userland application. .Bl -tag -width indent .It Fn autoreq_setino Set the request .Fa req inode to .Fa ino , this is typically unused. .It Fn autoreq_seterrno set the error returned to the application sending the request, typically this is left alone, or set to ENOENT if the request is for a non-existent name. The default error is no error. Meaning the application will see a successful return. .It Fn autoreq_setaux used to set the auxiliary data for a request, currently used to set the dirent structures for serving a readdir request. Default is no auxiliary data. .It Fn autoreq_seteof used to set the eof flag for readdir requests (default is not eof.) .El .Pp The functions .Fn autoh_togglepath and .Fn autoh_togglefd are used to set options on an .Xr autofs 9 directory via .Fa path and .Fa fd respectively. The .Fa pid argument should be set to the pid of the process serving .Xr autofs 9 requests, or -1 to disable the option. The options are .Bl -tag -width AUTO_INDIRECT .It Fa AUTO_MOUNTER set this process as the one responsible for the .Xr autofs 9 node, if this process exits, then requests into the autofs will begin to fail. .It Fa AUTO_BROWSE dispatch directory read requests for this node to the process identified by .Fa pid . Specifically, calls to .Xr getdirentries 2 and .Xr getdents 2 will be routed to userland after the current actual directory contents are read into userland. .It Fa AUTO_DIRECT Set the directory as a mount trigger. Any request to enter the directory will trigger a callback into the process .Fa pid . .It Fa AUTO_INDIRECT Set the directory as an indirect trigger. Any request for an entry inside the directory will be routed to the process identified by .Fa pid . .El .Sh EXAMPLES See /usr/share/examples/autofs/driver/ .Sh HISTORY The .Nm utility first appeared in .Fx 6.0 . .Sh AUTHORS This manual page and the autofs file system suite were written by .An Alfred Perlstein .