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 $ 26.\" $DragonFly: src/share/man/man9/make_dev.9,v 1.3 2006/05/26 19:39:40 swildner Exp $ 27.\" 28.Dd August 28, 2009 29.Os 30.Dt MAKE_DEV 9 31.Sh NAME 32.Nm destroy_dev , 33.Nm destroy_only_dev , 34.Nm devfs_scan_callback , 35.Nm dev_ops_intercept , 36.Nm dev_ops_remove_all , 37.Nm dev_ops_remove_minor , 38.Nm dev_ops_restore , 39.Nm make_dev , 40.Nm make_dev_alias , 41.Nm make_only_dev , 42.Nm reference_dev , 43.Nm release_dev 44.Nd "device entry manipulation functions" 45.Sh SYNOPSIS 46.In sys/types.h 47.In sys/conf.h 48.Ft void 49.Fn destroy_dev "cdev_t dev" 50.Ft void 51.Fn destroy_only_dev "cdev_t dev" 52.Ft int 53.Fn devfs_scan_callback "devfs_scan_t *callback" 54.Ft struct dev_ops * 55.Fn dev_ops_intercept "cdev_t dev" "struct dev_ops *iops" 56.Ft int 57.Fn dev_ops_remove_all "struct dev_ops *ops" 58.Ft void 59.Fn dev_ops_restore "cdev_t dev" "struct dev_ops *oops" 60.Ft int 61.Fn dev_ops_remove_minor "struct dev_ops *ops" "int minor" 62.Ft cdev_t 63.Fn make_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "char *fmt" ... 64.Ft int 65.Fn make_dev_alias "cdev_t target" "const char *fmt" ... 66.Ft cdev_t 67.Fn make_only_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... 68.Ft cdev_t 69.Fn reference_dev "cdev_t dev" 70.Ft void 71.Fn release_dev "cdev_t dev" 72.Sh DESCRIPTION 73The 74.Fn make_dev 75function creates a 76.Vt cdev_t 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. 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 . 88The permissions of the file specified in 89.Fa perms 90are defined in 91.In sys/stat.h : 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 117The 118.Fa ops 119argument is a pointer to a 120.Vt dev_ops 121data structure, which is defined as follows: 122.Bd -literal 123struct dev_ops { 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; 132 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 149}; 150.Ed 151.Pp 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 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 181.Fn make_only_dev 182creates a 183.Vt cdev_t 184structure and initializes it the same way 185.Fn make_dev 186would, but the device will not appear in the 187.Xr devfs 5 188namespace. 189.Pp 190.Fn destroy_dev 191takes the returned 192.Vt cdev_t 193from 194.Fn make_dev 195and destroys the registration for that device. 196It should not be used to destroy a 197.Vt cdev_t 198created by 199.Fn make_only_dev . 200.Pp 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. 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. 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 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 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 310.Sh HISTORY 311The 312.Fn make_dev 313and 314.Fn destroy_dev 315functions first appeared in 316.Fx 4.0 . 317.Pp 318A major overhaul of these functions occurred in 319.Dx 2.3 320with the addition of 321.Xr devfs 5 . 322