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.\" 27.Dd September 11, 2009 28.Os 29.Dt MAKE_DEV 9 30.Sh NAME 31.Nm destroy_dev , 32.Nm destroy_only_dev , 33.Nm devfs_scan_callback , 34.Nm dev_ops_intercept , 35.Nm dev_ops_remove_all , 36.Nm dev_ops_remove_minor , 37.Nm dev_ops_restore , 38.Nm make_dev , 39.Nm make_dev_alias , 40.Nm make_only_dev , 41.Nm reference_dev , 42.Nm release_dev 43.Nd "device entry manipulation functions" 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/conf.h 47.In sys/devfs.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_dev_covering "struct dev_ops *ops" "cdev_t rdev" "int minor" "uid_t uid" "gid_t gid" "int perms" "char *fmt" ... 68.Ft cdev_t 69.Fn make_only_dev "struct dev_ops *ops" "int minor" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... 70.Ft cdev_t 71.Fn reference_dev "cdev_t dev" 72.Ft void 73.Fn release_dev "cdev_t dev" 74.Sh DESCRIPTION 75The 76.Fn make_dev 77function creates a 78.Vt cdev_t 79structure for a new device and makes the device name visible in the 80.Xr devfs 5 81mount points. 82The device's name must be unique. 83The name is the expansion of 84.Fa fmt 85and following arguments as 86.Xr kprintf 9 87would print it. 88The name determines its path under 89.Pa /dev . 90The permissions of the file specified in 91.Fa perms 92are defined in 93.In sys/stat.h : 94.Pp 95.Bd -literal -offset indent -compact 96#define S_IRWXU 0000700 /* RWX mask for owner */ 97#define S_IRUSR 0000400 /* R for owner */ 98#define S_IWUSR 0000200 /* W for owner */ 99#define S_IXUSR 0000100 /* X for owner */ 100 101#define S_IRWXG 0000070 /* RWX mask for group */ 102#define S_IRGRP 0000040 /* R for group */ 103#define S_IWGRP 0000020 /* W for group */ 104#define S_IXGRP 0000010 /* X for group */ 105 106#define S_IRWXO 0000007 /* RWX mask for other */ 107#define S_IROTH 0000004 /* R for other */ 108#define S_IWOTH 0000002 /* W for other */ 109#define S_IXOTH 0000001 /* X for other */ 110 111#define S_ISUID 0004000 /* set user id on execution */ 112#define S_ISGID 0002000 /* set group id on execution */ 113#define S_ISVTX 0001000 /* sticky bit */ 114#ifndef _POSIX_SOURCE 115#define S_ISTXT 0001000 116#endif 117.Ed 118.Pp 119The 120.Fa ops 121argument is a pointer to a 122.Vt dev_ops 123data structure, which is defined as follows: 124.Bd -literal 125struct dev_ops { 126 struct { 127 const char *name; /* base name, e.g. 'da' */ 128 int maj; /* major device number */ 129 u_int flags; /* D_XXX flags */ 130 void *data; /* custom driver data */ 131 int refs; /* ref count */ 132 int id; 133 } head; 134 135#define dev_ops_first_field d_default 136 d_default_t *d_default; 137 d_open_t *d_open; 138 d_close_t *d_close; 139 d_read_t *d_read; 140 d_write_t *d_write; 141 d_ioctl_t *d_ioctl; 142 d_mmap_t *d_mmap; 143 d_strategy_t *d_strategy; 144 d_dump_t *d_dump; 145 d_psize_t *d_psize; 146 d_kqfilter_t *d_kqfilter; 147 d_clone_t *d_clone; /* clone from base dev_ops */ 148 d_revoke_t *d_revoke; 149#define dev_ops_last_field d_revoke 150}; 151.Ed 152.Pp 153While one can and should initialize the 154.Fa name 155and 156.Fa maj 157fields, they are effectively ignored. 158Device major numbers are assigned automatically out of an internal pool of 159major numbers, so there is no need to specify a unique major number in the 160.Vt dev_ops 161structure. 162.Pp 163Every member of the 164.Fn d_xxx_t 165family is defined as: 166.Bd -literal 167typedef int d_xxx_t (struct dev_xxx_args *ap); 168.Ed 169.Pp 170Therefore, if one wants to implement a 171.Fn mydev_open 172function, this is the way: 173.Bd -literal 174d_open_t mydev_open; 175 176int 177mydev_open(struct dev_open_args *ap) 178{ 179} 180.Ed 181.Pp 182.Fn make_dev_covering 183is equivalent to make_dev, except that it also takes an argument 184.Vt cdev_t rdev 185which is set as the backing device for the newly created device. 186This function should be used whenever a device is created covering 187another raw device, as the disk subsystem does. 188.Pp 189.Fn make_only_dev 190creates a 191.Vt cdev_t 192structure and initializes it the same way 193.Fn make_dev 194would, but the device will not appear in the 195.Xr devfs 5 196namespace. 197.Pp 198.Fn destroy_dev 199takes the returned 200.Vt cdev_t 201from 202.Fn make_dev 203and destroys the registration for that device. 204It should not be used to destroy a 205.Vt cdev_t 206created by 207.Fn make_only_dev . 208.Pp 209.Fn destroy_only_dev 210takes the returned 211.Vt cdev_t 212from 213.Fn make_only_dev 214and destroys the registration for that device. 215It should not be used to destroy a 216.Vt cdev_t 217created by 218.Fn make_dev . 219.Pp 220.Fn make_dev_alias 221creates an automatic 222.Xr devfs 5 223link (alias) with the given name to the 224.Vt cdev_t 225specified by 226.Fa target . 227The 228.Vt cdev_t 229must have been created either by 230.Fn make_dev 231or bt a clone handler. 232Aliases are alternative names for devices in the 233.Xr devfs 5 234namespace. 235The lifetime of an alias is that of its associated 236.Vt cdev_t . 237Once the 238.Vt cdev_t 239is removed or destroyed, the alias is also destroyed and its name is 240removed from the 241.Xr devfs 5 242namespace. 243.Pp 244.Fn reference_dev 245adds a reference to 246.Fa dev . 247Callers generally add their own references when they are going to store a device 248node in a variable for long periods of time, to prevent a disassociation from 249freeing the node. 250.Pp 251.Fn release_dev 252releases a reference on 253.Fa dev . 254The device will be terminated when the last reference has been released. 255.Pp 256.Fn dev_ops_intercept 257intercepts the device operations vector of 258.Fa dev 259with 260.Fa iops . 261The old 262.Vt dev_ops 263is returned which may be used in a subsequent 264.Fn dev_ops_restore 265call. 266The function sets the 267.Dv SI_INTERCEPTED 268flag in 269.Fa dev . 270.Pp 271.Fn dev_ops_restore 272restores the device operations vector of 273.Fa dev 274to 275.Fa oops . 276Also it unsets the 277.Dv SI_INTERCEPTED 278flag in 279.Fa dev . 280.Pp 281.Fn dev_ops_remove_all 282destroys all the 283.Vt cdev_t 284with the given 285.Fa ops 286and removes the devices from the 287.Xr devfs 5 288namespace. 289This function is useful when uninitializing a driver. 290.Pp 291.Fn dev_ops_remove_minor 292destroys all the 293.Vt cdev_t 294with the given 295.Fa ops 296and 297.Fa minor 298and removes the devices from the 299.Xr devfs 5 300namespace. 301.Pp 302.Fn devfs_scan_callback 303calls the given 304.Fa callback 305function for every device registered in 306.Xr devfs 5 . 307The 308.Fa callback 309function has the following form: 310.Bd -literal 311devfs_scan_t mydev_scan_callback; 312 313void 314mydev_scan_callback(cdev_t dev) 315{ 316}; 317.Ed 318.Sh HISTORY 319The 320.Fn make_dev 321and 322.Fn destroy_dev 323functions first appeared in 324.Fx 4.0 . 325.Pp 326A major overhaul of these functions occurred in 327.Dx 2.3 328with the addition of 329.Xr devfs 5 . 330