MAKE_AUTOCLONE_DEV(9)

NAME
make_autoclone_dev, destroy_autoclone_dev, devfs_clone_bitmap_init, devfs_clone_bitmap_uninit, devfs_clone_bitmap_chk, devfs_clone_bitmap_set, devfs_clone_bitmap_get, devfs_clone_bitmap_put, DEVFS_DECLARE_CLONE_BITMAP, DEVFS_DEFINE_CLONE_BITMAP, DEVFS_CLONE_BITMAP - device clone functions

SYNOPSIS
#include <sys/types.h>
#include <sys/conf.h>
#include <sys/devfs.h>
cdev_t
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, ...);
void
destroy_autoclone_dev(cdev_t dev, struct devfs_bitmap *bitmap);
void
devfs_clone_bitmap_init(struct devfs_bitmap *bitmap);
void
devfs_clone_bitmap_uninit(struct devfs_bitmap *bitmap);
int
devfs_clone_bitmap_chk(struct devfs_bitmap *bitmap, int unit);
int
devfs_clone_bitmap_set(struct devfs_bitmap *bitmap, int unit);
int
devfs_clone_bitmap_get(struct devfs_bitmap *bitmap, int limit);
void
devfs_clone_bitmap_put(struct devfs_bitmap *bitmap, int unit);
DEVFS_DECLARE_CLONE_BITMAP(name);
DEVFS_DEFINE_CLONE_BITMAP(name);
DEVFS_CLONE_BITMAP(name);

DESCRIPTION
make_autoclone_dev() creates a cdev_t with the default ops, visible in the devfs(5) namespace, that will invoke the clone handler specified by nhandler when it is opened. If the bitmap argument is specified, it will be initialized using devfs_clone_bitmap_init().

The clone handler must be defined as follows:

    d_clone_t mydev_clone;
    int
    mydev_clone(struct dev_clone_args *ap)
    {
    };

When called, the handler is passed a pointer to a populated dev_clone_args structure, which is defined as follows:

    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;
    };

The a_head.a_dev is the cdev_t of the accessed autoclone device. The a_name and a_namelen are the registered clonable base name and its length, as specified to make_autoclone_dev(). The a_mode and a_cred contain the mode and credential passed to the open() of the autoclone device.

The clone handler must set a_dev to a new cdev_t that is returned by a call to make_only_dev(). The new cdev_t will be automatically made visible and linked into devfs(5) namespace, as if it was created with make_dev(). Thus, destroy_dev() should be used to destroy the cloned cdev_t once it is no longer required, usually during close().

destroy_autoclone_dev() destroys a cdev_t created by make_autoclone_dev() unregistering its clone handler and (if non-NULL) also uninitializes its bitmap using devfs_clone_bitmap_uninit().

devfs_clone_bitmap_init() initializes the given clone bitmap so it is ready to use.

devfs_clone_bitmap_uninit() frees the memory associated with the specified clone bitmap and leaves it unusable.

devfs_clone_bitmap_chk() checks if unit is in use (set) and returns 1 if it is; otherwise 0 is returned.

devfs_clone_bitmap_set() marks unit in the bitmap as used, so further calls to devfs_clone_bitmap_get() cannot retrieve it. The function returns -1 if the unit is already allocated, otherwise 0. 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 devfs_clone_bitmap_set() on them.

devfs_clone_bitmap_get() will return the first unused unit number and also mark it as used in the bitmap. If the limit argument is greater than 0, the requested unit number cannot be greater than the given limit. The function returns -1 if no more units are available.

devfs_clone_bitmap_put() marks unit in the bitmap as unused so further calls to devfs_clone_bitmap_get() can retrieve it again. It is recommended that the associated device be destroyed prior to making the unit available in the bitmap again, to avoid racing against a new clone.

The DEVFS_DEFINE_CLONE_BITMAP() macro defines a clone bitmap with the specified name. As long as the name specified is unique, this macro can be used to define global variables. Similarly, DEVFS_DECLARE_CLONE_BITMAP() declares a clone bitmap.

The DEVFS_CLONE_BITMAP() is a macro which expands the specified name to the full name of a clone bitmap. It is used in conjunction with DEVFS_DEFINE_CLONE_BITMAP() and DEVFS_DECLARE_CLONE_BITMAP(), as it uses the same name.

SEE ALSO
devfs(5), destroy_dev(9), make_dev(9), make_only_dev(9)

HISTORY
The devfs(5) clone facilities and the associated functions all appeared in DragonFly 2.3.

AUTHORS
Alex Hornung