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 September 11, 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_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_poll_t *d_poll; 143 d_mmap_t *d_mmap; 144 d_strategy_t *d_strategy; 145 d_dump_t *d_dump; 146 d_psize_t *d_psize; 147 d_kqfilter_t *d_kqfilter; 148 d_clone_t *d_clone; /* clone from base dev_ops */ 149 d_revoke_t *d_revoke; 150#define dev_ops_last_field d_revoke 151}; 152.Ed 153.Pp 154While one can and should initialize the 155.Fa name 156and 157.Fa maj 158fields, they are effectively ignored. 159Device major numbers are assigned automatically out of an internal pool of 160major numbers, so there is no need to specify a unique major number in the 161.Vt dev_ops 162structure. 163.Pp 164Every member of the 165.Fn d_xxx_t 166family is defined as: 167.Bd -literal 168typedef int d_xxx_t (struct dev_xxx_args *ap); 169.Ed 170.Pp 171Therefore, if one wants to implement a 172.Fn mydev_open 173function, this is the way: 174.Bd -literal 175d_open_t mydev_open; 176 177int 178mydev_open(struct dev_open_args *ap) 179{ 180} 181.Ed 182.Pp 183.Fn make_dev_covering 184is equivalent to make_dev, except that it also takes an argument 185.Vt cdev_t rdev 186which is set as the backing device for the newly created device. 187This function should be used whenever a device is created covering 188another raw device, as the disk subsystem does. 189.Pp 190.Fn make_only_dev 191creates a 192.Vt cdev_t 193structure and initializes it the same way 194.Fn make_dev 195would, but the device will not appear in the 196.Xr devfs 5 197namespace. 198.Pp 199.Fn destroy_dev 200takes the returned 201.Vt cdev_t 202from 203.Fn make_dev 204and destroys the registration for that device. 205It should not be used to destroy a 206.Vt cdev_t 207created by 208.Fn make_only_dev . 209.Pp 210.Fn destroy_only_dev 211takes the returned 212.Vt cdev_t 213from 214.Fn make_only_dev 215and destroys the registration for that device. 216It should not be used to destroy a 217.Vt cdev_t 218created by 219.Fn make_dev . 220.Pp 221.Fn make_dev_alias 222creates an automatic 223.Xr devfs 5 224link (alias) with the given name to the 225.Vt cdev_t 226specified by 227.Fa target . 228The 229.Vt cdev_t 230must have been created either by 231.Fn make_dev 232or bt a clone handler. 233Aliases are alternative names for devices in the 234.Xr devfs 5 235namespace. 236The lifetime of an alias is that of its associated 237.Vt cdev_t . 238Once the 239.Vt cdev_t 240is removed or destroyed, the alias is also destroyed and its name is 241removed from the 242.Xr devfs 5 243namespace. 244.Pp 245.Fn reference_dev 246adds a reference to 247.Fa dev . 248Callers generally add their own references when they are going to store a device 249node in a variable for long periods of time, to prevent a disassociation from 250freeing the node. 251.Pp 252.Fn release_dev 253releases a reference on 254.Fa dev . 255The device will be terminated when the last reference has been released. 256.Pp 257.Fn dev_ops_intercept 258intercepts the device operations vector of 259.Fa dev 260with 261.Fa iops . 262The old 263.Vt dev_ops 264is returned which may be used in a subsequent 265.Fn dev_ops_restore 266call. 267The function sets the 268.Dv SI_INTERCEPTED 269flag in 270.Fa dev . 271.Pp 272.Fn dev_ops_restore 273restores the device operations vector of 274.Fa dev 275to 276.Fa oops . 277Also it unsets the 278.Dv SI_INTERCEPTED 279flag in 280.Fa dev . 281.Pp 282.Fn dev_ops_remove_all 283destroys all the 284.Vt cdev_t 285with the given 286.Fa ops 287and removes the devices from the 288.Xr devfs 5 289namespace. 290This function is useful when uninitializing a driver. 291.Pp 292.Fn dev_ops_remove_minor 293destroys all the 294.Vt cdev_t 295with the given 296.Fa ops 297and 298.Fa minor 299and removes the devices from the 300.Xr devfs 5 301namespace. 302.Pp 303.Fn devfs_scan_callback 304calls the given 305.Fa callback 306function for every device registered in 307.Xr devfs 5 . 308The 309.Fa callback 310function has the following form: 311.Bd -literal 312devfs_scan_t mydev_scan_callback; 313 314void 315mydev_scan_callback(cdev_t dev) 316{ 317}; 318.Ed 319.Sh HISTORY 320The 321.Fn make_dev 322and 323.Fn destroy_dev 324functions first appeared in 325.Fx 4.0 . 326.Pp 327A major overhaul of these functions occurred in 328.Dx 2.3 329with the addition of 330.Xr devfs 5 . 331