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