Update the make_dev(9) manual page for devfs.
[dragonfly.git] / share / man / man9 / make_dev.9
CommitLineData
984263bc
MD
1.\" Copyright (c) 1999 Chris Costello
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: src/share/man/man9/make_dev.9,v 1.2.2.3 2001/12/17 11:30:18 ru Exp $
44cb301e 26.\" $DragonFly: src/share/man/man9/make_dev.9,v 1.3 2006/05/26 19:39:40 swildner Exp $
984263bc 27.\"
1e811a6e 28.Dd August 28, 2009
984263bc
MD
29.Os
30.Dt MAKE_DEV 9
31.Sh NAME
f7ca11e0 32.Nm destroy_dev ,
1e811a6e
SW
33.Nm destroy_only_dev ,
34.Nm devfs_scan_callback ,
f7ca11e0 35.Nm dev_ops_intercept ,
1e811a6e
SW
36.Nm dev_ops_remove_all ,
37.Nm dev_ops_remove_minor ,
f7ca11e0 38.Nm dev_ops_restore ,
984263bc 39.Nm make_dev ,
1e811a6e
SW
40.Nm make_dev_alias ,
41.Nm make_only_dev ,
f7ca11e0
SW
42.Nm reference_dev ,
43.Nm release_dev
44.Nd "device entry manipulation functions"
984263bc
MD
45.Sh SYNOPSIS
46.In sys/types.h
47.In sys/conf.h
984263bc 48.Ft void
f7ca11e0 49.Fn destroy_dev "cdev_t dev"
1e811a6e
SW
50.Ft void
51.Fn destroy_only_dev "cdev_t dev"
f7ca11e0 52.Ft int
1e811a6e 53.Fn devfs_scan_callback "devfs_scan_t *callback"
f7ca11e0
SW
54.Ft struct dev_ops *
55.Fn dev_ops_intercept "cdev_t dev" "struct dev_ops *iops"
f7ca11e0 56.Ft int
1e811a6e 57.Fn dev_ops_remove_all "struct dev_ops *ops"
f7ca11e0
SW
58.Ft void
59.Fn dev_ops_restore "cdev_t dev" "struct dev_ops *oops"
60.Ft int
1e811a6e 61.Fn dev_ops_remove_minor "struct dev_ops *ops" "int minor"
f7ca11e0
SW
62.Ft cdev_t
63.Fn make_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "char *fmt" ...
1e811a6e
SW
64.Ft int
65.Fn make_dev_alias "cdev_t target" "const char *fmt" ...
f7ca11e0 66.Ft cdev_t
1e811a6e 67.Fn make_only_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ...
f7ca11e0
SW
68.Ft cdev_t
69.Fn reference_dev "cdev_t dev"
70.Ft void
71.Fn release_dev "cdev_t dev"
984263bc
MD
72.Sh DESCRIPTION
73The
74.Fn make_dev
75function creates a
f7ca11e0 76.Vt cdev_t
1e811a6e
SW
77structure for a new device and makes the device name visible in the
78.Xr devfs 5
79mount points.
80The device's name must be unique.
f7ca11e0
SW
81The name is the expansion of
82.Fa fmt
83and following arguments as
84.Xr kprintf 9
85would print it.
86The name determines its path under
87.Pa /dev .
984263bc 88The permissions of the file specified in
f7ca11e0 89.Fa perms
984263bc 90are defined in
44cb301e 91.In sys/stat.h :
984263bc
MD
92.Pp
93.Bd -literal -offset indent -compact
94#define S_IRWXU 0000700 /* RWX mask for owner */
95#define S_IRUSR 0000400 /* R for owner */
96#define S_IWUSR 0000200 /* W for owner */
97#define S_IXUSR 0000100 /* X for owner */
98
99#define S_IRWXG 0000070 /* RWX mask for group */
100#define S_IRGRP 0000040 /* R for group */
101#define S_IWGRP 0000020 /* W for group */
102#define S_IXGRP 0000010 /* X for group */
103
104#define S_IRWXO 0000007 /* RWX mask for other */
105#define S_IROTH 0000004 /* R for other */
106#define S_IWOTH 0000002 /* W for other */
107#define S_IXOTH 0000001 /* X for other */
108
109#define S_ISUID 0004000 /* set user id on execution */
110#define S_ISGID 0002000 /* set group id on execution */
111#define S_ISVTX 0001000 /* sticky bit */
112#ifndef _POSIX_SOURCE
113#define S_ISTXT 0001000
114#endif
115.Ed
116.Pp
1e811a6e
SW
117The
118.Fa ops
119argument is a pointer to a
f7ca11e0
SW
120.Vt dev_ops
121data structure, which is defined as follows:
122.Bd -literal
123struct dev_ops {
1e811a6e
SW
124 struct {
125 const char *name; /* base name, e.g. 'da' */
126 int maj; /* major device number */
127 u_int flags; /* D_XXX flags */
128 void *data; /* custom driver data */
129 int refs; /* ref count */
130 int id;
131 } head;
f7ca11e0 132
1e811a6e
SW
133#define dev_ops_first_field d_default
134 d_default_t *d_default;
135 d_open_t *d_open;
136 d_close_t *d_close;
137 d_read_t *d_read;
138 d_write_t *d_write;
139 d_ioctl_t *d_ioctl;
140 d_poll_t *d_poll;
141 d_mmap_t *d_mmap;
142 d_strategy_t *d_strategy;
143 d_dump_t *d_dump;
144 d_psize_t *d_psize;
145 d_kqfilter_t *d_kqfilter;
146 d_clone_t *d_clone; /* clone from base dev_ops */
147 d_revoke_t *d_revoke;
148#define dev_ops_last_field d_revoke
f7ca11e0
SW
149};
150.Ed
151.Pp
1e811a6e
SW
152While one can and should initialize the
153.Fa name
154and
155.Fa maj
156fields, they are effectively ignored.
157Device major numbers are assigned automatically out of an internal pool of
158major numbers, so there is no need to specify a unique major number in the
159.Vt dev_ops
160structure.
161.Pp
f7ca11e0
SW
162Every member of the
163.Fn d_xxx_t
164family is defined as:
165.Bd -literal
166typedef int d_xxx_t (struct dev_xxx_args *ap);
167.Ed
168.Pp
169Therefore, if one wants to implement a
170.Fn mydev_open
171function, this is the way:
172.Bd -literal
173d_open_t mydev_open;
174
175int
176mydev_open(struct dev_open_args *ap)
177{
178}
179.Ed
180.Pp
1e811a6e
SW
181.Fn make_only_dev
182creates a
183.Vt cdev_t
184structure and initializes it the same way
f7ca11e0 185.Fn make_dev
1e811a6e
SW
186would, but the device will not appear in the
187.Xr devfs 5
188namespace.
f7ca11e0 189.Pp
984263bc 190.Fn destroy_dev
f7ca11e0
SW
191takes the returned
192.Vt cdev_t
984263bc
MD
193from
194.Fn make_dev
195and destroys the registration for that device.
1e811a6e
SW
196It should not be used to destroy a
197.Vt cdev_t
198created by
199.Fn make_only_dev .
f7ca11e0 200.Pp
1e811a6e
SW
201.Fn destroy_only_dev
202takes the returned
203.Vt cdev_t
204from
205.Fn make_only_dev
206and destroys the registration for that device.
207It should not be used to destroy a
208.Vt cdev_t
209created by
210.Fn make_dev .
211.Pp
212.Fn make_dev_alias
213creates an automatic
214.Xr devfs 5
215link (alias) with the given name to the
216.Vt cdev_t
217specified by
218.Fa target .
219The
220.Vt cdev_t
221must have been created either by
222.Fn make_dev
223or bt a clone handler.
224Aliases are alternative names for devices in the
225.Xr devfs 5
226namespace.
227The lifetime of an alias is that of its associated
228.Vt cdev_t .
229Once the
230.Vt cdev_t
231is removed or destroyed, the alias is also destroyed and its name is
232removed from the
233.Xr devfs 5
234namespace.
f7ca11e0
SW
235.Pp
236.Fn reference_dev
237adds a reference to
238.Fa dev .
239Callers generally add their own references when they are going to store a device
240node in a variable for long periods of time, to prevent a disassociation from
241freeing the node.
f7ca11e0
SW
242.Pp
243.Fn release_dev
244releases a reference on
245.Fa dev .
246The device will be terminated when the last reference has been released.
247.Pp
f7ca11e0
SW
248.Fn dev_ops_intercept
249intercepts the device operations vector of
250.Fa dev
251with
252.Fa iops .
253The old
254.Vt dev_ops
255is returned which may be used in a subsequent
256.Fn dev_ops_restore
257call.
258The function sets the
259.Dv SI_INTERCEPTED
260flag in
261.Fa dev .
262.Pp
263.Fn dev_ops_restore
264restores the device operations vector of
265.Fa dev
266to
267.Fa oops .
268Also it unsets the
269.Dv SI_INTERCEPTED
270flag in
271.Fa dev .
272.Pp
1e811a6e
SW
273.Fn dev_ops_remove_all
274destroys all the
275.Vt cdev_t
276with the given
277.Fa ops
278and removes the devices from the
279.Xr devfs 5
280namespace.
281This function is useful when uninitializing a driver.
282.Pp
283.Fn dev_ops_remove_minor
284destroys all the
285.Vt cdev_t
286with the given
287.Fa ops
288and
289.Fa minor
290and removes the devices from the
291.Xr devfs 5
292namespace.
293.Pp
294.Fn devfs_scan_callback
295calls the given
296.Fa callback
297function for every device registered in
298.Xr devfs 5 .
299The
300.Fa callback
301function has the following form:
302.Bd -literal
303devfs_scan_t mydev_scan_callback;
304
305void
306mydev_scan_callback(cdev_t dev)
307{
308};
309.Ed
984263bc
MD
310.Sh HISTORY
311The
312.Fn make_dev
313and
314.Fn destroy_dev
315functions first appeared in
316.Fx 4.0 .
1e811a6e
SW
317.Pp
318A major overhaul of these functions occured in DragonFly 2.3 with the addition
319of
320.Xr devfs 5 .