'\" te
.\"  Copyright (c) 2002 Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH devlinks 1M "15 Jul 2002" "SunOS 5.11" "System Administration Commands"
.SH NAME
devlinks \- adds /dev entries for miscellaneous devices and pseudo-devices
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/devlinks\fR [\fB-d\fR] [\fB-r\fR \fIrootdir\fR] [\fB-t\fR \fItable-file\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBdevfsadm\fR(1M) is now the preferred command for \fB/dev\fR and
\fB/devices\fR and should be used instead of \fBdevlinks\fR.
.sp
.LP
\fBdevlinks\fR creates symbolic links from the \fB/dev\fR directory tree to the
actual block- and character-special device nodes under the \fB/devices\fR
directory tree. The links are created according to specifications found in the
\fItable-file\fR (by default \fB/etc/devlink.tab\fR).
.sp
.LP
\fBdevlinks\fR is called each time the system is reconfiguration-booted, and
can only be run after \fBdrvconfig\fR(1M) is run.
.sp
.LP
The \fItable-file\fR (normally \fB/etc/devlink.tab\fR) is an ASCII file, with
one line per record. Comment lines, which must contain a hash character
(`\fB#\fR') as their first character, are allowed. Each entry must contain at
least two fields, but may contain three fields. Fields are separated by single
TAB characters.
.sp
.LP
The fields are:
.sp
.ne 2
.mk
.na
\fB\fIdevfs-spec\fR\fR
.ad
.RS 18n
.rt  
Specification of devinfo nodes that will have links created for them. This
specification consists of one or more keyword-value pairs, where the keyword is
separated from the value by an equal-sign (`\fB=\fR'), and keyword-value pairs
are separated from one another by semicolons.
.sp
The possible keywords are:
.sp
.ne 2
.mk
.na
\fB\fItype\fR\fR
.ad
.RS 12n
.rt  
The devinfo device type. Possible values are specified in
\fBddi_create_minor_node\fR(9F)
.RE

.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 12n
.rt  
The name of the node. This is the portion of the \fB/devices\fR tree entry name
that occurs before the first `\fB@\fR' or `\fB:\fR' character.
.RE

.sp
.ne 2
.mk
.na
\fB\fIaddr\fR[\fIn\fR]\fR
.ad
.RS 12n
.rt  
The address portion of a node name. This is the portion of a node name that
occurs between the `\fB@\fR' and the `\fB:\fR' characters. It is possible that
a node may have a name without an address part, which is the case for many of
the pseudo-device nodes. If a number is given after the \fIaddr\fR it specifies
a match of a particular comma-separated subfield of the address field:
\fIaddr1\fR matches the first subfield, \fIaddr2\fR matches the second, and so
on. \fIaddr0\fR is the same as \fIaddr\fR and matches the whole field.
.RE

.sp
.ne 2
.mk
.na
\fB\fIminor\fR[\fIn\fR]\fR
.ad
.RS 12n
.rt  
The minor portion of a node name \(mi the portion of the name after the
`\fB:\fR'. As with \fIaddr\fR above, a number after the \fIminor\fR keyword
specifies a subfield to match.
.RE

Of these four specifications, only the \fItype\fR specification must always be
present.
.RE

.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 18n
.rt  
Specification of the \fB/dev\fR links that correspond to the devinfo nodes.
This field allows \fBdevlinks\fR to determine matching \fB/dev\fR names for the
\fB/devices\fR nodes it has found. The specification of this field uses
escape-sequences to allow portions of the \fB/devices\fR name to be included in
the \fB/dev\fR name, \fIor\fR to allow a counter to be used in creating node
names. If a counter is used to create a name, the portion of the name before
the counter must be specified absolutely, and all names in the
\fB/dev/\fR-subdirectory that match (up to and including the counter) are
considered to be subdevices of the same device. This means that they should all
point to the same directory, \fBname\fR and \fBaddress\fR under the
\fB/devices/\fR-tree
.sp
The possible escape-sequences are:
.sp
.ne 2
.mk
.na
\fB\fB\eD\fR\fR
.ad
.RS 8n
.rt  
Substitute the \fBdevice-name\fR (name) portion of the corresponding devinfo
node-name.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\eA\fR\fIn\fR\fR
.ad
.RS 8n
.rt  
Substitute the \fIn\fRth component of the \fBaddress\fR component of the
corresponding devinfo node name. Sub-components are separated by commas, and
sub-component \fB0\fR is the whole \fBaddress\fR component.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\eM\fR\fIn\fR\fR
.ad
.RS 8n
.rt  
Substitute the \fIn\fRth sub-component of the \fBminor\fR component of the
corresponding devinfo node name. Sub-components are separated by commas, and
sub-component \fB0\fR is the whole \fBminor\fR component.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\eN\fR\fIn\fR\fR
.ad
.RS 8n
.rt  
Substitute the value of a 'counter' starting at \fIn\fR. There can be only one
counter for each dev-spec, and counter-values will be selected so they are as
low as possible while not colliding with already-existing link names.
.sp
In a dev-spec the \fBcounter\fR sequence should not be followed by a digit,
either explicitly or as a result of another escape-sequence expansion. If this
occurs, it would not be possible to correctly match already-existing links to
their counter entries, since it would not be possible to unambiguously parse
the already-existing \fB/dev\fR-name.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIextra-dev-link\fR\fR
.ad
.RS 18n
.rt  
Optional specification of an extra \fB/dev\fR link that points to the initial
\fB/dev\fR link (specified in field 2). This field may contain a \fBcounter\fR
escape-sequence (as described for the \fIdev-spec\fR field) but may not contain
any of the other escape-sequences. It provides a way to specify an alias of a
particular \fB/dev\fR name.
.RE

.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-d\fR\fR
.ad
.RS 17n
.rt  
Debugging mode \(mi print out all \fBdevinfo\fR nodes found, and indicate what
links would be created, but do not do anything.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-r\fR \fIrootdir\fR\fR
.ad
.RS 17n
.rt  
Use \fIrootdir\fR as the root of the \fB/dev\fR and \fB/devices\fR directories
under which the device nodes and links are created. Changing the root directory
does not change the location of the \fB/etc/devlink.tab\fR default table, nor
is the root directory applied to the filename supplied to the \fB-t\fR option.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-t\fR \fItable-file\fR\fR
.ad
.RS 17n
.rt  
Set the table file used by \fBdevlinks\fR to specify the links that must be
created. If this option is not given, \fB/etc/devlink.tab\fR is used. This
option gives a way to instruct \fBdevlinks\fR just to perform a particular
piece of work, since just the links-types that \fBdevlinks\fR is supposed to
create can be specified in a command-file and fed to \fBdevlinks\fR.
.RE

.SH ERRORS
.sp
.LP
If \fBdevlinks\fR finds an error in a line of the \fItable-file\fR it prints a
warning message on its standard output and goes on to the next line in the
\fItable-file\fR without performing any of the actions specified by the
erroneous rule.
.sp
.LP
If it cannot create a link for some filesystem-related reason it prints an
error-message and continues with the current rule.
.sp
.LP
If it cannot read necessary data it prints an error message and continues with
the next \fItable-file\fR line.
.SH EXAMPLES
.LP
\fBExample 1 \fRUsing the \fB/etc/devlink.tab\fR Fields
.sp
.LP
The following are examples of the \fB/etc/devlink.tab\fR fields:

.sp
.in +2
.nf
type=pseudo;name=win	win\eM0
type=ddi_display	framebuffer/\eM0	fb\eN0
.fi
.in -2

.sp
.LP
The first example states that all devices of type \fBpseudo\fR with a name
component of \fBwin\fR will be linked to \fB/dev/win\fR\fIx,\fR where \fIx\fR
is the minor-component of the \fIdevinfo-name\fR (this is always a single-digit
number for the \fBwin\fR driver).

.sp
.LP
The second example states that all devinfo nodes of type \fBddi_display\fR will
be linked to entries under the \fB/dev/framebuffer\fR directory, with names
identical to the entire minor component of the \fB/devices\fR name. In addition
an extra link will be created pointing from \fB/dev/fb\fR\fIn\fR to the entry
under \fB/dev/framebuffer\fR. This entry will use a counter to end the name.

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/dev\fR\fR
.ad
.RS 20n
.rt  
entries for the miscellaneous devices for general use
.RE

.sp
.ne 2
.mk
.na
\fB\fB/devices\fR\fR
.ad
.RS 20n
.rt  
device nodes
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/devlink.tab\fR\fR
.ad
.RS 20n
.rt  
the default rule-file
.RE

.SH SEE ALSO
.sp
.LP
\fBdevfsadm\fR(1M), \fBattributes\fR(5), \fBdevfs\fR(7FS),
\fBddi_create_minor_node\fR(9F)
.SH BUGS
.sp
.LP
It is very easy to construct mutually-contradictory link specifications, or
specifications that can never be matched. The program does not check for these
conditions.