path: root/lib/libautofs/libautofs.3

.\" Copyright (c) 2004 Alfred Perlstein <alfred@FreeBSD.org>
.\" 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 .