Add the make_autoclone_dev(9) manual page.
authorSascha Wildner <saw@online.de>
Mon, 7 Sep 2009 14:56:21 +0000 (16:56 +0200)
committerSascha Wildner <saw@online.de>
Mon, 7 Sep 2009 14:56:21 +0000 (16:56 +0200)
Submitted-by: alexh
share/man/man9/Makefile
share/man/man9/make_autoclone_dev.9 [new file with mode: 0644]

index b645845..e917fe5 100644 (file)
@@ -99,6 +99,7 @@ MAN=  accept_filter.9 \
        ksignal.9 \
        ktr.9 \
        lock.9 \
+       make_autoclone_dev.9 \
        make_dev.9 \
        mbuf.9 \
        MD5.9 \
@@ -469,6 +470,17 @@ MLINKS+=lock.9 lockcount.9 \
        lock.9 lockmgr.9 \
        lock.9 lockmgr_printinfo.9 \
        lock.9 lockstatus.9
+MLINKS+=make_autoclone_dev.9 destroy_autoclone_dev.9 \
+       make_autoclone_dev.9 DEVFS_CLONE_BITMAP.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_chk.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_fff.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_get.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_init.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_put.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_rst.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_set.9 \
+       make_autoclone_dev.9 devfs_clone_bitmap_uninit.9 \
+       make_autoclone_dev.9 DEVFS_DECLARE_CLONE_BITMAP.9
 MLINKS+=make_dev.9 destroy_dev.9 \
        make_dev.9 destroy_only_dev.9 \
        make_dev.9 devfs_scan_callback.9 \
diff --git a/share/man/man9/make_autoclone_dev.9 b/share/man/man9/make_autoclone_dev.9
new file mode 100644 (file)
index 0000000..4c802fa
--- /dev/null
@@ -0,0 +1,249 @@
+.\"
+.\" Copyright (c) 2009
+.\"    The DragonFly Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\" 3. Neither the name of The DragonFly Project nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific, prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd September 7, 2009
+.Os
+.Dt MAKE_AUTOCLONE_DEV 9
+.Sh NAME
+.Nm make_autoclone_dev ,
+.Nm destroy_autoclone_dev ,
+.Nm devfs_clone_bitmap_init ,
+.Nm devfs_clone_bitmap_uninit ,
+.Nm devfs_clone_bitmap_fff ,
+.Nm devfs_clone_bitmap_chk ,
+.Nm devfs_clone_bitmap_set ,
+.Nm devfs_clone_bitmap_rst ,
+.Nm devfs_clone_bitmap_get ,
+.Nm devfs_clone_bitmap_put ,
+.Nm DEVFS_DECLARE_CLONE_BITMAP ,
+.Nm DEVFS_CLONE_BITMAP
+.Nd device clone functions
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/conf.h
+.In sys/devfs.h
+.Ft cdev_t
+.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" ...
+.Ft void
+.Fn destroy_autoclone_dev "cdev_t dev" "struct devfs_bitmap *bitmap"
+.Ft void
+.Fn devfs_clone_bitmap_init "struct devfs_bitmap *bitmap"
+.Ft void
+.Fn devfs_clone_bitmap_uninit "struct devfs_bitmap *bitmap"
+.Ft void
+.Fn devfs_clone_bitmap_fff "struct devfs_bitmap *bitmap"
+.Ft int
+.Fn devfs_clone_bitmap_chk "struct devfs_bitmap *bitmap, int unit"
+.Ft void
+.Fn devfs_clone_bitmap_set "struct devfs_bitmap *bitmap, int unit"
+.Ft void
+.Fn devfs_clone_bitmap_rst "struct devfs_bitmap *bitmap, int unit"
+.Ft int
+.Fn devfs_clone_bitmap_get "struct devfs_bitmap *bitmap, int limit"
+.Ft void
+.Fn devfs_clone_bitmap_put "struct devfs_bitmap *bitmap, int unit"
+.Fn DEVFS_DECLARE_CLONE_BITMAP "name"
+.Fn DEVFS_CLONE_BITMAP "name"
+.Sh DESCRIPTION
+.Fn make_autoclone_dev
+creates a
+.Vt cdev_t
+with the default
+.Fa ops ,
+visible in the
+.Xr devfs 5
+namespace, that (when opened) will invoke the clone handler specified by
+.Fa nhandler .
+If a
+.Vt devfs_bitmap *
+is specified, the given
+.Fa bitmap
+is initialized using
+.Fn devfs_clone_bitmap_init .
+.Pp
+The clone handler must be defined as follows:
+.Bd -literal
+d_clone_t mydev_clone;
+
+int
+mydev_clone(struct dev_clone_args *ap)
+{
+};
+.Ed
+.Pp
+When called, the handler is passed a pointer to a populated
+.Vt dev_clone_args
+structure, which is defined as follows:
+.Bd -literal
+struct dev_clone_args {
+        struct dev_generic_args a_head;
+        struct cdev     *a_dev;
+        const char      *a_name;
+        size_t           a_namelen;
+        struct ucred    *a_cred;
+        int              a_mode;
+};
+.Ed
+.Pp
+.Fa a_head.a_dev
+is the
+.Vt cdev_t
+of the accessed autoclone device.
+.Fa a_name
+and
+.Fa a_namelen
+are the registered clonable base name and its length, as specified to
+.Fn make_autoclone_dev .
+.Fa a_mode
+and
+.Fa a_cred
+contain the mode and cred passed to the autoclone device's
+.Fn open .
+.Pp
+The clone handler must set
+.Fa a_dev
+to a new
+.Vt cdev_t ,
+returned by a call to
+.Fn make_only_dev .
+.Fa a_dev
+may also be set to
+.Dv NULL ,
+in which case the
+.Fn open
+will ultimately fail with
+.Er ENXIO .
+If
+.Fa a_dev
+is
+.Pf non- Ns Dv NULL ,
+it is automatically made visible and linked into
+.Xr devfs 5
+as if it was created with
+.Fn make_dev .
+Thus,
+.Fn destroy_dev
+should be used to destroy the cloned
+.Vt cdev_t
+once it is no longer required,
+usually during
+.Fn close .
+.Pp
+.Fn destroy_autoclone_dev
+destroys a
+.Vt cdev_t
+created by
+.Fn make_autoclone_dev
+unregistering its clone handler and (if non-NULL) also uninitializes its
+.Fa bitmap
+using
+.Fn devfs_clone_bitmap_uninit .
+.Pp
+.Fn devfs_clone_bitmap_init
+initializes the given clone
+.Fa bitmap
+so it is ready to use.
+.Pp
+.Fn devfs_clone_bitmap_uninit
+frees the memory associated with the specified clone
+.Fa bitmap
+and leaves it unusable.
+.Pp
+.Fn devfs_clone_bitmap_fff
+returns the first unused unit in
+.Fa bitmap .
+To use this unit, it has to be acquired by a call to
+.Fn devfs_clone_bitmap_set .
+.Pp
+.Fn devfs_clone_bitmap_chk
+checks if
+.Fa unit
+is in use (set) and returns 1 if it is; otherwise 0 is returned.
+.Pp
+.Fn devfs_clone_bitmap_set
+marks
+.Fa unit
+in
+.Fa bitmap
+as used, so further calls to
+.Fn devfs_clone_bitmap_fff
+or
+.Fn devfs_clone_bitmap_get
+cannot retrieve it.
+If one intends to use a clone handler along with preallocated devices, it
+is recommended to block the unit numbers of the preallocated devices by
+calling
+.Fn devfs_clone_bitmap_set
+on them.
+.Pp
+.Fn devfs_clone_bitmap_rst
+marks
+.Fa unit
+in the
+.Fa bitmap
+as unused so further calls to
+.Fn devfs_clone_bitmap_fff
+or
+.Fn devfs_clone_bitmap_get
+can retrieve it again.
+.Fn devfs_clone_bitmap_put
+is an alias for
+.Fn devfs_clone_bitmap_rst .
+.Pp
+.Fn devfs_clone_bitmap_get
+is a shortcut to
+.Fn devfs_clone_bitmap_fff
+and
+.Fn devfs_clone_bitmap_set .
+It will return the first unused unit number and also mark it as used.
+.Pp
+The
+.Fn DEVFS_DECLARE_CLONE_BITMAP
+macro declares a clone bitmap with the specified
+.Fa name .
+As long as the name specified is unique, this macro can be used to declare
+global variables.
+.Pp
+The
+.Fn DEVFS_CLONE_BITMAP
+is a macro which expands the specified
+.Fa name
+to the full name of a clone bitmap.
+It is used in conjunction with
+.Fn DEVFS_DECLARE_CLONE_BITMAP ,
+as it uses the same name.
+.Sh HISTORY
+The
+.Xr devfs 5
+clone facilities and the associated functions all appeared in
+.Dx 2.3 .
+.Sh AUTHOR
+.An Alex Hornung