| blob | 992857dc3fcffbc230fc66628db754b55c396ce5 |
1 '\" te
2 .\" Copyright (c) 2002 Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH DEVLINKS 1M "Jul 15, 2002"
7 .SH NAME
8 devlinks \- adds /dev entries for miscellaneous devices and pseudo-devices
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/devlinks\fR [\fB-d\fR] [\fB-r\fR \fIrootdir\fR] [\fB-t\fR \fItable-file\fR]
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 \fBdevfsadm\fR(1M) is now the preferred command for \fB/dev\fR and
19 \fB/devices\fR and should be used instead of \fBdevlinks\fR.
20 .sp
21 .LP
22 \fBdevlinks\fR creates symbolic links from the \fB/dev\fR directory tree to the
23 actual block- and character-special device nodes under the \fB/devices\fR
24 directory tree. The links are created according to specifications found in the
25 \fItable-file\fR (by default \fB/etc/devlink.tab\fR).
26 .sp
27 .LP
28 \fBdevlinks\fR is called each time the system is reconfiguration-booted, and
29 can only be run after \fBdrvconfig\fR(1M) is run.
30 .sp
31 .LP
32 The \fItable-file\fR (normally \fB/etc/devlink.tab\fR) is an ASCII file, with
33 one line per record. Comment lines, which must contain a hash character
34 (`\fB#\fR') as their first character, are allowed. Each entry must contain at
35 least two fields, but may contain three fields. Fields are separated by single
36 TAB characters.
37 .sp
38 .LP
39 The fields are:
40 .sp
41 .ne 2
42 .na
43 \fB\fIdevfs-spec\fR\fR
44 .ad
45 .RS 18n
46 Specification of devinfo nodes that will have links created for them. This
47 specification consists of one or more keyword-value pairs, where the keyword is
48 separated from the value by an equal-sign (`\fB=\fR'), and keyword-value pairs
49 are separated from one another by semicolons.
50 .sp
51 The possible keywords are:
52 .sp
53 .ne 2
54 .na
55 \fB\fItype\fR\fR
56 .ad
57 .RS 12n
58 The devinfo device type. Possible values are specified in
59 \fBddi_create_minor_node\fR(9F)
60 .RE
62 .sp
63 .ne 2
64 .na
65 \fB\fIname\fR\fR
66 .ad
67 .RS 12n
68 The name of the node. This is the portion of the \fB/devices\fR tree entry name
69 that occurs before the first `\fB@\fR' or `\fB:\fR' character.
70 .RE
72 .sp
73 .ne 2
74 .na
75 \fB\fIaddr\fR[\fIn\fR]\fR
76 .ad
77 .RS 12n
78 The address portion of a node name. This is the portion of a node name that
79 occurs between the `\fB@\fR' and the `\fB:\fR' characters. It is possible that
80 a node may have a name without an address part, which is the case for many of
81 the pseudo-device nodes. If a number is given after the \fIaddr\fR it specifies
82 a match of a particular comma-separated subfield of the address field:
83 \fIaddr1\fR matches the first subfield, \fIaddr2\fR matches the second, and so
84 on. \fIaddr0\fR is the same as \fIaddr\fR and matches the whole field.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fIminor\fR[\fIn\fR]\fR
91 .ad
92 .RS 12n
93 The minor portion of a node name \(mi the portion of the name after the
94 `\fB:\fR'. As with \fIaddr\fR above, a number after the \fIminor\fR keyword
95 specifies a subfield to match.
96 .RE
98 Of these four specifications, only the \fItype\fR specification must always be
99 present.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fIname\fR\fR
106 .ad
107 .RS 18n
108 Specification of the \fB/dev\fR links that correspond to the devinfo nodes.
109 This field allows \fBdevlinks\fR to determine matching \fB/dev\fR names for the
110 \fB/devices\fR nodes it has found. The specification of this field uses
111 escape-sequences to allow portions of the \fB/devices\fR name to be included in
112 the \fB/dev\fR name, \fIor\fR to allow a counter to be used in creating node
113 names. If a counter is used to create a name, the portion of the name before
114 the counter must be specified absolutely, and all names in the
115 \fB/dev/\fR-subdirectory that match (up to and including the counter) are
116 considered to be subdevices of the same device. This means that they should all
117 point to the same directory, \fBname\fR and \fBaddress\fR under the
118 \fB/devices/\fR-tree
119 .sp
120 The possible escape-sequences are:
121 .sp
122 .ne 2
123 .na
124 \fB\fB\eD\fR\fR
125 .ad
126 .RS 8n
127 Substitute the \fBdevice-name\fR (name) portion of the corresponding devinfo
128 node-name.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fB\eA\fR\fIn\fR\fR
135 .ad
136 .RS 8n
137 Substitute the \fIn\fRth component of the \fBaddress\fR component of the
138 corresponding devinfo node name. Sub-components are separated by commas, and
139 sub-component \fB0\fR is the whole \fBaddress\fR component.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fB\eM\fR\fIn\fR\fR
146 .ad
147 .RS 8n
148 Substitute the \fIn\fRth sub-component of the \fBminor\fR component of the
149 corresponding devinfo node name. Sub-components are separated by commas, and
150 sub-component \fB0\fR is the whole \fBminor\fR component.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fB\eN\fR\fIn\fR\fR
157 .ad
158 .RS 8n
159 Substitute the value of a 'counter' starting at \fIn\fR. There can be only one
160 counter for each dev-spec, and counter-values will be selected so they are as
161 low as possible while not colliding with already-existing link names.
162 .sp
163 In a dev-spec the \fBcounter\fR sequence should not be followed by a digit,
164 either explicitly or as a result of another escape-sequence expansion. If this
165 occurs, it would not be possible to correctly match already-existing links to
166 their counter entries, since it would not be possible to unambiguously parse
167 the already-existing \fB/dev\fR-name.
168 .RE
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fB\fIextra-dev-link\fR\fR
176 .ad
177 .RS 18n
178 Optional specification of an extra \fB/dev\fR link that points to the initial
179 \fB/dev\fR link (specified in field 2). This field may contain a \fBcounter\fR
180 escape-sequence (as described for the \fIdev-spec\fR field) but may not contain
181 any of the other escape-sequences. It provides a way to specify an alias of a
182 particular \fB/dev\fR name.
183 .RE
185 .SH OPTIONS
186 .sp
187 .LP
188 The following options are supported:
189 .sp
190 .ne 2
191 .na
192 \fB\fB-d\fR\fR
193 .ad
194 .RS 17n
195 Debugging mode \(mi print out all \fBdevinfo\fR nodes found, and indicate what
196 links would be created, but do not do anything.
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fB-r\fR \fIrootdir\fR\fR
203 .ad
204 .RS 17n
205 Use \fIrootdir\fR as the root of the \fB/dev\fR and \fB/devices\fR directories
206 under which the device nodes and links are created. Changing the root directory
207 does not change the location of the \fB/etc/devlink.tab\fR default table, nor
208 is the root directory applied to the filename supplied to the \fB-t\fR option.
209 .RE
211 .sp
212 .ne 2
213 .na
214 \fB\fB-t\fR \fItable-file\fR\fR
215 .ad
216 .RS 17n
217 Set the table file used by \fBdevlinks\fR to specify the links that must be
218 created. If this option is not given, \fB/etc/devlink.tab\fR is used. This
219 option gives a way to instruct \fBdevlinks\fR just to perform a particular
220 piece of work, since just the links-types that \fBdevlinks\fR is supposed to
221 create can be specified in a command-file and fed to \fBdevlinks\fR.
222 .RE
224 .SH ERRORS
225 .sp
226 .LP
227 If \fBdevlinks\fR finds an error in a line of the \fItable-file\fR it prints a
228 warning message on its standard output and goes on to the next line in the
229 \fItable-file\fR without performing any of the actions specified by the
230 erroneous rule.
231 .sp
232 .LP
233 If it cannot create a link for some filesystem-related reason it prints an
234 error-message and continues with the current rule.
235 .sp
236 .LP
237 If it cannot read necessary data it prints an error message and continues with
238 the next \fItable-file\fR line.
239 .SH EXAMPLES
240 .LP
241 \fBExample 1 \fRUsing the \fB/etc/devlink.tab\fR Fields
242 .sp
243 .LP
244 The following are examples of the \fB/etc/devlink.tab\fR fields:
246 .sp
247 .in +2
248 .nf
249 type=pseudo;name=win win\eM0
250 type=ddi_display framebuffer/\eM0 fb\eN0
251 .fi
252 .in -2
254 .sp
255 .LP
256 The first example states that all devices of type \fBpseudo\fR with a name
257 component of \fBwin\fR will be linked to \fB/dev/win\fR\fIx,\fR where \fIx\fR
258 is the minor-component of the \fIdevinfo-name\fR (this is always a single-digit
259 number for the \fBwin\fR driver).
261 .sp
262 .LP
263 The second example states that all devinfo nodes of type \fBddi_display\fR will
264 be linked to entries under the \fB/dev/framebuffer\fR directory, with names
265 identical to the entire minor component of the \fB/devices\fR name. In addition
266 an extra link will be created pointing from \fB/dev/fb\fR\fIn\fR to the entry
267 under \fB/dev/framebuffer\fR. This entry will use a counter to end the name.
269 .SH FILES
270 .sp
271 .ne 2
272 .na
273 \fB\fB/dev\fR\fR
274 .ad
275 .RS 20n
276 entries for the miscellaneous devices for general use
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fB/devices\fR\fR
283 .ad
284 .RS 20n
285 device nodes
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fB/etc/devlink.tab\fR\fR
292 .ad
293 .RS 20n
294 the default rule-file
295 .RE
297 .SH SEE ALSO
298 .sp
299 .LP
300 \fBdevfsadm\fR(1M), \fBattributes\fR(5), \fBdevfs\fR(7FS),
301 \fBddi_create_minor_node\fR(9F)
302 .SH BUGS
303 .sp
304 .LP
305 It is very easy to construct mutually-contradictory link specifications, or
306 specifications that can never be matched. The program does not check for these
307 conditions.