1.\" 2.\" Copyright (c) 2009 3.\" The DragonFly Project. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 3. Neither the name of The DragonFly Project nor the names of its 16.\" contributors may be used to endorse or promote products derived 17.\" from this software without specific, prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd December 2, 2012 33.Dt MAKE_AUTOCLONE_DEV 9 34.Os 35.Sh NAME 36.Nm make_autoclone_dev , 37.Nm destroy_autoclone_dev , 38.Nm devfs_clone_bitmap_init , 39.Nm devfs_clone_bitmap_uninit , 40.Nm devfs_clone_bitmap_fff , 41.Nm devfs_clone_bitmap_chk , 42.Nm devfs_clone_bitmap_set , 43.Nm devfs_clone_bitmap_get , 44.Nm devfs_clone_bitmap_put , 45.Nm DEVFS_DECLARE_CLONE_BITMAP , 46.Nm DEVFS_DEFINE_CLONE_BITMAP , 47.Nm DEVFS_CLONE_BITMAP 48.Nd device clone functions 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/conf.h 52.In sys/devfs.h 53.Ft cdev_t 54.Fn make_autoclone_dev "struct dev_ops *ops" "struct devfs_bitmap *bitmap" "d_clone_t *nhandler" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" "..." 55.Ft void 56.Fn destroy_autoclone_dev "cdev_t dev" "struct devfs_bitmap *bitmap" 57.Ft void 58.Fn devfs_clone_bitmap_init "struct devfs_bitmap *bitmap" 59.Ft void 60.Fn devfs_clone_bitmap_uninit "struct devfs_bitmap *bitmap" 61.Ft int 62.Fn devfs_clone_bitmap_fff "struct devfs_bitmap *bitmap" 63.Ft int 64.Fn devfs_clone_bitmap_chk "struct devfs_bitmap *bitmap" "int unit" 65.Ft void 66.Fn devfs_clone_bitmap_set "struct devfs_bitmap *bitmap" "int unit" 67.Ft int 68.Fn devfs_clone_bitmap_get "struct devfs_bitmap *bitmap" "int limit" 69.Ft void 70.Fn devfs_clone_bitmap_put "struct devfs_bitmap *bitmap" "int unit" 71.Fn DEVFS_DECLARE_CLONE_BITMAP "name" 72.Fn DEVFS_DEFINE_CLONE_BITMAP "name" 73.Fn DEVFS_CLONE_BITMAP "name" 74.Sh DESCRIPTION 75.Fn make_autoclone_dev 76creates a 77.Vt cdev_t 78with the default 79.Fa ops , 80visible in the 81.Xr devfs 5 82namespace, that (when opened) will invoke the clone handler specified by 83.Fa nhandler . 84If a 85.Vt devfs_bitmap * 86is specified, the given 87.Fa bitmap 88is initialized using 89.Fn devfs_clone_bitmap_init . 90.Pp 91The clone handler must be defined as follows: 92.Bd -literal 93d_clone_t mydev_clone; 94 95int 96mydev_clone(struct dev_clone_args *ap) 97{ 98}; 99.Ed 100.Pp 101When called, the handler is passed a pointer to a populated 102.Vt dev_clone_args 103structure, which is defined as follows: 104.Bd -literal 105struct dev_clone_args { 106 struct dev_generic_args a_head; 107 struct cdev *a_dev; 108 const char *a_name; 109 size_t a_namelen; 110 struct ucred *a_cred; 111 int a_mode; 112}; 113.Ed 114.Pp 115.Fa a_head.a_dev 116is the 117.Vt cdev_t 118of the accessed autoclone device. 119.Fa a_name 120and 121.Fa a_namelen 122are the registered clonable base name and its length, as specified to 123.Fn make_autoclone_dev . 124.Fa a_mode 125and 126.Fa a_cred 127contain the mode and cred passed to the autoclone device's 128.Fn open . 129.Pp 130The clone handler must set 131.Fa a_dev 132to a new 133.Vt cdev_t , 134returned by a call to 135.Fn make_only_dev . 136.Fa a_dev 137may also be set to 138.Dv NULL , 139in which case the 140.Fn open 141will ultimately fail with 142.Er ENXIO . 143If 144.Fa a_dev 145is 146.Pf non- Ns Dv NULL , 147it is automatically made visible and linked into 148.Xr devfs 5 149as if it was created with 150.Fn make_dev . 151Thus, 152.Fn destroy_dev 153should be used to destroy the cloned 154.Vt cdev_t 155once it is no longer required, 156usually during 157.Fn close . 158.Pp 159.Fn destroy_autoclone_dev 160destroys a 161.Vt cdev_t 162created by 163.Fn make_autoclone_dev 164unregistering its clone handler and (if non-NULL) also uninitializes its 165.Fa bitmap 166using 167.Fn devfs_clone_bitmap_uninit . 168.Pp 169.Fn devfs_clone_bitmap_init 170initializes the given clone 171.Fa bitmap 172so it is ready to use. 173.Pp 174.Fn devfs_clone_bitmap_uninit 175frees the memory associated with the specified clone 176.Fa bitmap 177and leaves it unusable. 178.Pp 179.Fn devfs_clone_bitmap_fff 180returns the first unused unit in 181.Fa bitmap . 182To use this unit, it has to be acquired by a call to 183.Fn devfs_clone_bitmap_set . 184.Pp 185.Fn devfs_clone_bitmap_chk 186checks if 187.Fa unit 188is in use (set) and returns 1 if it is; otherwise 0 is returned. 189.Pp 190.Fn devfs_clone_bitmap_set 191marks 192.Fa unit 193in 194.Fa bitmap 195as used, so further calls to 196.Fn devfs_clone_bitmap_fff 197or 198.Fn devfs_clone_bitmap_get 199cannot retrieve it. 200If one intends to use a clone handler along with preallocated devices, it 201is recommended to block the unit numbers of the preallocated devices by 202calling 203.Fn devfs_clone_bitmap_set 204on them. 205.Pp 206.Fn devfs_clone_bitmap_put 207marks 208.Fa unit 209in the 210.Fa bitmap 211as unused so further calls to 212.Fn devfs_clone_bitmap_fff 213or 214.Fn devfs_clone_bitmap_get 215can retrieve it again. 216.Pp 217.Fn devfs_clone_bitmap_get 218is a shortcut to 219.Fn devfs_clone_bitmap_fff 220and 221.Fn devfs_clone_bitmap_set . 222It will return the first unused unit number and also mark it as used. 223.Pp 224The 225.Fn DEVFS_DEFINE_CLONE_BITMAP 226macro defines a clone bitmap with the specified 227.Fa name . 228As long as the name specified is unique, this macro can be used to define 229global variables. 230Similarly, 231.Fn DEVFS_DECLARE_CLONE_BITMAP 232declares a clone bitmap. 233.Pp 234The 235.Fn DEVFS_CLONE_BITMAP 236is a macro which expands the specified 237.Fa name 238to the full name of a clone bitmap. 239It is used in conjunction with 240.Fn DEVFS_DEFINE_CLONE_BITMAP 241and 242.Fn DEVFS_DECLARE_CLONE_BITMAP , 243as it uses the same name. 244.Sh HISTORY 245The 246.Xr devfs 5 247clone facilities and the associated functions all appeared in 248.Dx 2.3 . 249.Sh AUTHOR 250.An Alex Hornung 251