devfsd.8

devfsd 驱动对linux的补丁支持

.\" Copyright (C) 1998-2002  Richard Gooch
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.\" Richard Gooch may be reached by email at  [e-mail]
.\" The postal address is:
.\"   Richard Gooch, c/o ATNF, P. O. Box 76, Epping, N.S.W., 2121, Australia.
.\"
.\"	devfsd.8		Richard Gooch	8-MAR-2002
.\"
.TH DEVFSD 8 "8 Mar 2002" "Linux System Daemons"

.SH NAME
devfsd \- optional daemon for managing devfs (the Linux Device
Filesystem)

.SH SYNOPSIS
.B devfsd
.B mntpnt
[
.B -v
]
[
.B -d
]
[
.B -t num
]
[
.B -D mask
]
[
.B -fg
]
[
.B -np
]

.SH DESCRIPTION
The \fIdevfsd\fP programme is a daemon, run by the system boot
scripts, which can provide for intelligent management of device
entries in the Device Filesystem (devfs). It is desirable to start the
daemon at the beginning of the boot scripts, in particular before
filesystem checks.
.PP
As part of its setup phase \fIdevfsd\fP creates certain symbolic
links which are compiled into the code. These links are required by
\fB/usr/src/linux/Documentation/devices.txt\fP. This behaviour may
change in future revisions.
.PP
\fIdevfsd\fP will read the special control file \fI.devfsd\fP in a
mounted devfs, listening for the creation and removal of device
entries (this is termed a change operation). For each change
operation, \fIdevfsd\fP can take many actions. The daemon will
normally run itself in the background and send messages to syslog.
.PP
The opening of the syslog service is automatically delayed until
\fI/dev/log\fP is created.
.PP
At startup, before switching to daemon mode, \fIdevfsd\fP will scan
the mounted device tree and will generate synthetic \fBREGISTER\fP
events for each leaf node and directory.

.SH OPTIONS
.TP
.B mntpnt
This specifies a mount point for where devfs is mounted. This is
typically "/dev". The daemon will change directory to this mount point
before opening any files.
.TP
.B \-v
This option will print the protocol version numbers for \fIdevfsd\fP
and the kernel-side protocol version provided by devfs itself. The
programme then exits.
.TP
.B \-d
Run \fIdevfsd\fP in debug mode. Used for debugging the kernel-side
protocol implemented by devfs. This also prints the protocol version
numbers. In this mode the daemon runs in the foreground.
.TP
.B \-t num
Set the trace level to \fInum\fP. If the level is greater than 0 then
output is sent to stderr rather than syslog(3). If the level is
greater than 1 then \fIdevfsd\fP will run in trace mode. Higher levels
yield more trace information.
.TP
.B \-D mask
Set the debug mask for devfs.
.TP
.B \-fg
Run the daemon in the foreground.
.TP
.B \-np
Exit after parsing the configuration file and processing synthetic
\fBREGISTER\fP events. Do not poll for events. This is primarily used
for creating compatibility entries without needing a daemon running in
the background.

.SH CONFIGURATION
The configuration file /etc/devfsd.conf configures the \fIdevfsd\fP
programme. It is a simple ASCII file with one configuration option per
line. Comment lines must start with a leading '#' character. Comment
lines and blank lines are ignored. Each configuration option is a
keyword followed by zero or more parameters, depending on the
option. The following section details the configuration options. Below
are the permitted keywords:
.TP
.B INCLUDE location
Include the configuration file named by \fIlocation\fP. Variable
expansion is applied to \fIlocation\fP (see the  section on VARIABLE
EXPANSION below). If this is a directory, then all files (except those
which start with '.') are read. This is recursive (i.e. files which
are in fact subdirectories are also read).

If the first character of \fIlocation\fP is "+",
then the rest of \fIlocation\fP is the name of an NIS map to load.
This operation is silently ignored if the NIS domain has not yet been
set (\fBSIGHUP\fP should then be sent after the NIS domain has been
set).
.TP
.B OPTIONAL_INCLUDE location
As above, except that if the file does not exist, it is silently
ignored.
.TP
.B CLEAR_CONFIG
Clear the current configuration.
.TP
.B RESTORE directory
This will restore entries previously saved under \fIdirectory\fP to
devfs. Only symbolic links or entries with the sticky bit set will be
restored. This action is taken as the configuration file is read. With
appropriate \fBCOPY\fP actions, complete persistence is acheived.
.PP
The config file can also be used to specify actions that should be
taken at specified events. Each line specifies an event and
action. Multiple actions (of the same or different types) per event
may be specified (one action per line). Events are processed in order,
with the first event config line being processed first. The syntax is:
.TP
.B EVENT devname ACTION [args...]
where \fIEVENT\fP is the event and \fIACTION\fP is the action to take
when the event occurs. The action is only taken when \fIdevname\fP
matches the name of the device entry affected (this does not include
the mount point for the filesystem). This is processed as a regular
expression. Some actions support extra arguments, passed as
\fIargs\fP.

Variable expansion is applied to the arguments (see the section on
VARIABLE EXPANSION below). After variable expansion, regular
expression substitution is performed (see the section on REGULAR
EXPRESSION SUBSTITUTION). Note that the following special variable
names are also recognised:
.RS
.TP
.B devpath
the full path name of the new device
.TP
.B devname
the name of the new device inside the devfs namespace
.TP
.B mode
the mode of the device entry in octal
.TP
.B uid
the user ID of the process or inode
.TP
.B gid
the group ID of the process or inode
.RE
.PP
The following events are recognised:
.TP
.B REGISTER
The device entry or directory was registered by a device driver.
.TP
.B UNREGISTER
The device entry was unregistered by a device driver.
.TP
.B ASYNC_OPEN
The inode was opened (the opening process does not wait for a
response).
.TP
.B CLOSE
The file was closed.
.TP
.B LOOKUP
An inode lookup was performed and there was no device entry. This
event is not sent if the initiating process is devfsd or one of its
children.
.TP
.B CHANGE
Some inode attributes were changed.
.TP
.B CREATE
An inode was created by a process.
.TP
.B DELETE
An inode was deleted by a process.
.PP
The following actions are recognised:
.TP
.B PERMISSIONS owner_and_group access_mode
\fIowner_and_group\fP specifies the owner and group that the file
should be set to. This must be of the form "user.group" and either
"user" or "group" component may be symbolic or numeric. To specify
that the user or group be left alone, use a numeric value of "-1" for
the respective component. \fIaccess_mode\fP specifies the access mode
the file should be set to. This must be either an octal value or a
symbolic string of nine characters with the form "rwxrwxrwx". Where
access is not given, a '-' character should be used in place
(e.g. "rw-rw-r--" gives read and write access to the user and group
and only read access to everybody else).
.TP
.B MODLOAD
This action will pass "/dev/$devname" (i.e. "/dev/" prefixed to the
device name) to the module loading facility. In addition, the
\fI/etc/modules.devfs\fP configuration file is used.
.TP
.B EXECUTE path [arg...]
This action allows you to run a programme. \fIpath\fP is the pathname
of the programme to run and \fIarg\fP is a set of optional arguments
passed to the programme (maximum 6). \fIpath\fP is the first argument
(i.e. argv[0]) passed to the programme.
.TP
.B MFUNCTION path function [arg...]
This action allows you to run a "main"-style function within a shared
object. \fIpath\fP is the pathname of the shared object, with the
special path of "GLOBAL" signifying all global symbols (e.g. from
libc). The default directory is \fB/lib/devfsd\fP. \fIfunction\fP is
the name of the function symbol to run and \fIarg\fP is a set of
optional arguments passed to the function (maximum 5). \fIpath\fP is
the first argument (i.e. argv[0]) passed to the function. The
prototype for this function is similar to the \fImain\fP function of C
programmes. The prototype is:

int func (int argc, char **argv);
.TP
.B CFUNCTION path function [arg...]
This action is similar to the \fBMFUNCTION\fP action, except for the
calling convention. The prototype for this function is:

int func (void *arg1, void *arg2, void *arg3, void *arg4, void *arg5);

Up to 5 arguments may be passed, each being of type \fIvoid *\fP. The
following special arguments are recognised:
.RS
.TP
.B EVENT
a \fIstruct devfsd_notify_struct *\fP is passed
.RE
.PP
.TP
.B COPY source destination
This action will copy the device type and permissions of \fIsource\fP
to \fIdestination\fP. The sticky bit is set on the destination inode
if the source inode was create manually (i.e. not by a driver or
\fIdevfsd\fP).
.TP
.B IGNORE
This action causes all subsequent processing for the event to be
ignored.
.TP
.B MKOLDCOMPAT
This action creates an "old" compatibility entry for the device.
.TP
.B MKNEWCOMPAT
This action creates a "new" compatibility entry for the device.
.TP
.B RMOLDCOMPAT
This action removes an "old" compatibility entry for the device.
.TP
.B RMNEWCOMPAT
This action removes a "new" compatibility entry for the device.

.SH VARIABLE EXPANSION
A subset of normal Bourne shell variable expansion is applied to
various expressions. The currently supported subset is:
\fI$variable\fP, \fI${variable}\fP and \fI${variable:-word}\fP.
Variables are taken from the environment. The following variable names
are also defined :
.TP
.B hostname
The hostname of the machine
.TP
.B mntpnt
The mount point for devfs

.SH REGULAR EXPRESSION SUBSTITUTION
Sections of the matched regular expression can be included in
an action.  Use \fI\\0\fP to refer to the entire regular expression
matched, \fI\\1\fP to refer to the first parenthesized subexpression,
\fI\\2\fP to refer to the second, and so on.  (Use \fI\\\\\fP to
include an actual backslash.)
.PP
See \fBdevfsd.conf\fP(5) for examples of regular expression
substitution.

.SH SIGNALS
\fIdevfsd\fP responds to signals in a variety of ways:
.TP
.B SIGINT
\fIdevfsd\fP will exit cleanly.
.TP
.B SIGTERM
\fIdevfsd\fP will exit cleanly.
.TP
.B SIGHUP
The configuration file is re-read and any shared objects are
reloaded. Then the mounted device tree is scanned and synthetic
\fBREGISTER\fP events are generated for each leaf node.
.TP
.B SIGUSR1
The configuration file is re-read and any shared objects are
reloaded. No synthetic \fBREGISTER\fP events are generated.

.SH EXAMPLES
.B Create and destroy "old" compatibility entries:
.RS
.nf
.if t .ft CW
REGISTER     .*           MKOLDCOMPAT
UNREGISTER   .*           RMOLDCOMPAT
.if t .ft P
.fi
.RE
.LP
.B Create and destroy "new" compatibility entries:
.RS
.nf
.if t .ft CW
REGISTER     .*           MKNEWCOMPAT
UNREGISTER   .*           RMNEWCOMPAT
.if t .ft P
.fi
.RE
.LP
.B Load modules:
.RS
.nf
.if t .ft CW
LOOKUP       .*           MODLOAD
.if t .ft P
.fi
.RE
.LP
.B Make and remove a symbolic link:
.RS
.nf
.if t .ft CW
REGISTER     mydir/mydev  CFUNCTION GLOBAL mksymlink $devname mydev
UNREGISTER   mydir/mydev  CFUNCTION GLOBAL unlink  mydev
.if t .ft P
.fi
.RE
.LP
.B Give sndusers group access to sound drivers
.RS
.nf
.if t .ft CW
REGISTER     sound/.*     PERMISSIONS root.sndusers rw-rw----
.if t .ft P
.fi
.RE

.SH FILES
.TP
.B /etc/devfsd.conf
the configuration file. If this file is missing or has zero size,
\fIdevfsd\fP will exit after its setup phase.
.TP
.B /etc/modules.devfs
the generic module configuration file (required for the \fBMODLOAD\fP
action), which is installed with \fIdevfsd\fP. This in turn includes
\fI/etc/modules.conf\fP

.SH CAVEATS
Make sure you understand the implications of regular expression
matching. For example, if you had a configuration line such as:

.B LOOKUP  cdrom  CFUNCTION  GLOBAL mksymlink ${mntpnt}/cdroms/cdrom0 $devpath

then referencing "/dev/cdrom1" will create the symbolic link
"/dev/cdrom1". Further, referencing "/dev/cdroms/1" would also create
the "/dev/cdroms/1" symbolic link. This is probably not what you want.
If there was not already a "/dev/cdroms" directory, then you would get
a "/dev/cdrom" symbolic link. Definately not what you want!
The correct configuration line would be:

.B LOOKUP  ^cdrom$  CFUNCTION GLOBAL mksymlink ${mntpnt}/cdroms/cdrom0 $devpath

.SH SEE ALSO
.BR init (8),
.BR devfsd.conf (5),
.BR modprobe (8)

.SH AUTHOR
Richard Gooch ([e-mail])

.SH AVAILABILITY
The Device Filesystem daemon is available from:
http://www.atnf.csiro.au/~rgooch/linux/

.SH FURTHER READING
It is strongly recommended to read the devfs FAQ, which contains
configuration tips. It is available at:
http://www.atnf.csiro.au/~rgooch/linux/docs/devfs.html

.SH MAILING LIST
A mailing list exists for devfs kernel patch and devfsd release
announcements. This list also has a small amount of discussion traffic
(a few messages per week). You may subscribe by sending a message to
\[e-mail]\fP with \fBsubscribe devfs\fP in the message
\fIbody\fP.