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 August 13, 2010 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_CLONE_BITMAP 47.Nd device clone functions 48.Sh SYNOPSIS 49.In sys/types.h 50.In sys/conf.h 51.In sys/devfs.h 52.Ft cdev_t 53.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" "..." 54.Ft void 55.Fn destroy_autoclone_dev "cdev_t dev" "struct devfs_bitmap *bitmap" 56.Ft void 57.Fn devfs_clone_bitmap_init "struct devfs_bitmap *bitmap" 58.Ft void 59.Fn devfs_clone_bitmap_uninit "struct devfs_bitmap *bitmap" 60.Ft int 61.Fn devfs_clone_bitmap_fff "struct devfs_bitmap *bitmap" 62.Ft int 63.Fn devfs_clone_bitmap_chk "struct devfs_bitmap *bitmap" "int unit" 64.Ft void 65.Fn devfs_clone_bitmap_set "struct devfs_bitmap *bitmap" "int unit" 66.Ft int 67.Fn devfs_clone_bitmap_get "struct devfs_bitmap *bitmap" "int limit" 68.Ft void 69.Fn devfs_clone_bitmap_put "struct devfs_bitmap *bitmap" "int unit" 70.Fn DEVFS_DECLARE_CLONE_BITMAP "name" 71.Fn DEVFS_CLONE_BITMAP "name" 72.Sh DESCRIPTION 73.Fn make_autoclone_dev 74creates a 75.Vt cdev_t 76with the default 77.Fa ops , 78visible in the 79.Xr devfs 5 80namespace, that (when opened) will invoke the clone handler specified by 81.Fa nhandler . 82If a 83.Vt devfs_bitmap * 84is specified, the given 85.Fa bitmap 86is initialized using 87.Fn devfs_clone_bitmap_init . 88.Pp 89The clone handler must be defined as follows: 90.Bd -literal 91d_clone_t mydev_clone; 92 93int 94mydev_clone(struct dev_clone_args *ap) 95{ 96}; 97.Ed 98.Pp 99When called, the handler is passed a pointer to a populated 100.Vt dev_clone_args 101structure, which is defined as follows: 102.Bd -literal 103struct dev_clone_args { 104 struct dev_generic_args a_head; 105 struct cdev *a_dev; 106 const char *a_name; 107 size_t a_namelen; 108 struct ucred *a_cred; 109 int a_mode; 110}; 111.Ed 112.Pp 113.Fa a_head.a_dev 114is the 115.Vt cdev_t 116of the accessed autoclone device. 117.Fa a_name 118and 119.Fa a_namelen 120are the registered clonable base name and its length, as specified to 121.Fn make_autoclone_dev . 122.Fa a_mode 123and 124.Fa a_cred 125contain the mode and cred passed to the autoclone device's 126.Fn open . 127.Pp 128The clone handler must set 129.Fa a_dev 130to a new 131.Vt cdev_t , 132returned by a call to 133.Fn make_only_dev . 134.Fa a_dev 135may also be set to 136.Dv NULL , 137in which case the 138.Fn open 139will ultimately fail with 140.Er ENXIO . 141If 142.Fa a_dev 143is 144.Pf non- Ns Dv NULL , 145it is automatically made visible and linked into 146.Xr devfs 5 147as if it was created with 148.Fn make_dev . 149Thus, 150.Fn destroy_dev 151should be used to destroy the cloned 152.Vt cdev_t 153once it is no longer required, 154usually during 155.Fn close . 156.Pp 157.Fn destroy_autoclone_dev 158destroys a 159.Vt cdev_t 160created by 161.Fn make_autoclone_dev 162unregistering its clone handler and (if non-NULL) also uninitializes its 163.Fa bitmap 164using 165.Fn devfs_clone_bitmap_uninit . 166.Pp 167.Fn devfs_clone_bitmap_init 168initializes the given clone 169.Fa bitmap 170so it is ready to use. 171.Pp 172.Fn devfs_clone_bitmap_uninit 173frees the memory associated with the specified clone 174.Fa bitmap 175and leaves it unusable. 176.Pp 177.Fn devfs_clone_bitmap_fff 178returns the first unused unit in 179.Fa bitmap . 180To use this unit, it has to be acquired by a call to 181.Fn devfs_clone_bitmap_set . 182.Pp 183.Fn devfs_clone_bitmap_chk 184checks if 185.Fa unit 186is in use (set) and returns 1 if it is; otherwise 0 is returned. 187.Pp 188.Fn devfs_clone_bitmap_set 189marks 190.Fa unit 191in 192.Fa bitmap 193as used, so further calls to 194.Fn devfs_clone_bitmap_fff 195or 196.Fn devfs_clone_bitmap_get 197cannot retrieve it. 198If one intends to use a clone handler along with preallocated devices, it 199is recommended to block the unit numbers of the preallocated devices by 200calling 201.Fn devfs_clone_bitmap_set 202on them. 203.Pp 204.Fn devfs_clone_bitmap_put 205marks 206.Fa unit 207in the 208.Fa bitmap 209as unused so further calls to 210.Fn devfs_clone_bitmap_fff 211or 212.Fn devfs_clone_bitmap_get 213can retrieve it again. 214.Pp 215.Fn devfs_clone_bitmap_get 216is a shortcut to 217.Fn devfs_clone_bitmap_fff 218and 219.Fn devfs_clone_bitmap_set . 220It will return the first unused unit number and also mark it as used. 221.Pp 222The 223.Fn DEVFS_DECLARE_CLONE_BITMAP 224macro declares a clone bitmap with the specified 225.Fa name . 226As long as the name specified is unique, this macro can be used to declare 227global variables. 228.Pp 229The 230.Fn DEVFS_CLONE_BITMAP 231is a macro which expands the specified 232.Fa name 233to the full name of a clone bitmap. 234It is used in conjunction with 235.Fn DEVFS_DECLARE_CLONE_BITMAP , 236as it uses the same name. 237.Sh HISTORY 238The 239.Xr devfs 5 240clone facilities and the associated functions all appeared in 241.Dx 2.3 . 242.Sh AUTHOR 243.An Alex Hornung 244