LIBAUTOFS(3)

NAME
libautofs - procedural interface to managing an autofs file system

SYNOPSIS
#include <libautofs.h>
int
autoh_get(const char *path, autoh_t *hndlp);
void
autoh_free(autoh_t hndl);
int
autoh_getall(autoh_t **hndlpp, int *cnt);
void
autoh_freeall(autoh_t *hndlep);
int
autoh_fd(autoh_t hndl);
const char *
autoh_mp(autoh_t hndl);
int
autoreq_get(autoh_t hndl, autoreq_t **reqpp, int *cntp);
void
autoreq_free(autoh_t hndl, autoreq_t *reqp);
int
autoreq_serv(autoh_t hndl, autoreq_t req);
enum autoreq_op
autoreq_getop(autoreq_t req);
const char *
autoreq_getpath(autoreq_t req);
autoino_t
autoreq_getino(autoreq_t req);
autoino_t
autoreq_getdirino(autoreq_t req);
void
autoreq_getaux(autoreq_t req, void **auxdatap, size_t *auxsizep);
void
autoreq_getoffset(autoreq_t req, off_t *offp);
void
autoreq_getxid(autoreq_t req, int *xidp);
void
autoreq_setino(autoreq_t req, autoino_t ino);
void
autoreq_seterrno(autoreq_t req, int errno);
void
autoreq_setaux(autoreq_t req, void *auxdata, size_t auxsize);
void
autoreq_seteof(autoreq_t req, int eof);
int
autoh_togglepath(autoh_t hndl, int toggle, pid_t pid, const char *path);
int
autoh_togglefd(autoh_t hndl, int toggle, pid_t pid, int fd);

DESCRIPTION
The libautofs library provides a "mostly" stable interface to the autofs(9) file system.

The interface to autofs(9) is managed via handles of type autoh_t and autoreq_t which refer to handles to autofs(9) mount points and requests respectively.

The autoh_get() function returns a handle to an autofs(9) file system based on the path parameter. The handle returned should be freed via the autoh_free() function.

The autoh_getall() function returns an array of handles to all mounted autofs(9) file systems, each of which should be released via the autoh_free() function or released en-mass via the autoh_freeall() function.

The autoh_fd() function returns a file descriptor that can be used with select(2) or poll(2) to check for "exceptional" data to detect an autofs(9) event. Users of select(2) should set the fd in the exceptfds fd_set. Users of poll(2) should set POLLPRI in the pollfd fds argument.

The autoh_mp() function returns the path to the autofs file system that the hndl is derived from.

The autoreq_get() function returns an array of autofs requests in reqpp, the number of requests is stored into cntp. Each request should be released using the autoreq_free() function.

Requests that are retrieved via the autoreq_get() are served via the "autoreq_" functions.

The following functions returns information about the request.

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 autofs(9) requires service from.

autoreq_getpath()
    return the path of the mountpoint associated with the request req.

autoreq_getino()
    return the inode associated with the request req.

autoreq_getdirno()
    return the directory inode associated with the request req.

autoreq_getaux()
    return the auxiliary data associated with the request req.

autoreq_getoffset()
    return the offset request associated with the request req. (used for readdir request)

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.

The following functions allow one to set the response sent to autofs(9) to the requesting userland application.

autoreq_setino()
    Set the request req inode to ino, this is typically unused.

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.

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.

autoreq_seteof()
    used to set the eof flag for readdir requests (default is not eof.)

The functions autoh_togglepath() and autoh_togglefd() are used to set options on an autofs(9) directory via path and fd respectively. The pid argument should be set to the pid of the process serving autofs(9) requests, or -1 to disable the option. The options are

AUTO_MOUNTER
    set this process as the one responsible for the autofs(9) node, if this process exits, then requests into the autofs will begin to fail.

AUTO_BROWSE
    dispatch directory read requests for this node to the process identified by pid. Specifically, calls to getdirentries(2) and getdents(2) will be routed to userland after the current actual directory contents are read into userland.

AUTO_DIRECT
    Set the directory as a mount trigger. Any request to enter the directory will trigger a callback into the process pid.

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 pid.

EXAMPLES
See /usr/share/examples/autofs/driver/

HISTORY
The libautofs utility first appeared in FreeBSD 6.0.

AUTHORS
This manual page and the autofs file system suite were written by Alfred Perlstein.