266 lines
7.2 KiB
Groff
266 lines
7.2 KiB
Groff
.\" 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
|
|
libarary provides a "mostly" stable interface to the
|
|
.Xr autofs 9
|
|
file system.
|
|
.Pp
|
|
The inteface 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 auxilliray 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-existant
|
|
name.
|
|
The default error is no error.
|
|
Meaning the application will see
|
|
a successful return.
|
|
.It Fn autoreq_setaux
|
|
used to set the auxilliray data for a request, currently used to set
|
|
the dirent structures for serving a readdir request.
|
|
Default is no
|
|
auxilliary 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 .
|