VND_CREATE(3VND)VND_CREATE(3VND)NAME
vnd_create, vnd_open, vnd_unlink, vnd_close - create, open, and destroy
vnd devices
SYNOPSIS
cc [ flag... ] file... -lvnd [ library... ]
#include <libvnd.h>
vnd_handle_t *vnd_create(const char *zonename, const char *datalink,
const char *linkname, vnd_errno_t *vnderr, int *syserr);
vnd_handle_t *vnd_open(const char *zonename, const char *linkname,
vnd_errno_t *vnderr, int *syserr);
int vnd_unlink(vnd_handle_t *vhp);
void vnd_close(vnd_handle_t *vhp);
DESCRIPTION
These functions create vnd devices, obtain handles to extant vnd
devices, and close handles to vnd devices, for use with the rest of
libvnd(3LIB).
The vnd_create function creates a new vnd device in the zone specified
by zonename. The zone name argument may be null, in which case the
caller's current zone is used instead. The vnd device and data link it
is created over must both be in the same zone. The datalink argument
indicates the name of the DLPI data link to create the vnd device over.
The linkname argument indicates the name of the new vnd device. The
linkname argument must be less than VND_NAMELEN characters long,
excluding the null terminator. It should be an alphanumeric string.
The only non-alphanumeric characters allowed are ':', '-', and ´_'.
Neither the datalink argument nor linkname argument may be NULL. A han‐
dle to the created device is returned to the caller. Once the vnd_cre‐
ate function returns, the device can be subsequently opened with a call
to vnd_open. The named device persists until a call to vnd_unlink or
the containing zone is halted. Creating a vnd device requires
PRIV_SYS_NET_CONFIG as well as PRIV_RAWACCESS. The arguments vnderr and
syserr are used to obtain errors in the cases where the call to
vnd_create fails. Both arguments may be NULL pointers, in which case
the more detailed error information is discarded.
The vnd_open function opens an existing vnd device and returns a unique
handle to that device. The vnd device to open is specified by both
zonename and linkname. The zonename argument specifies what zone to
look for the vnd device in. The linkname specifies the name of the
link. The zonename argument may be NULL. If it is, the current zone is
used. Similar to vnd_create, the integer values pointed to by the argu‐
ments vnderr and syserr will be filled in with additional error infor‐
mation in the cases where a call to vnd_open fails. Both arguments may
be NULL to indicate that the error information is not requested, though
this is not recommended.
The vnd_unlink function unlinks the vnd device specified by the vnd
handle vhp. This unlink is similar to the use of unlink in a file sys‐
tem. After a call to unlink, the vnd device will no longer be accessi‐
ble by callers to vnd_open and the name will be available for use in
vnd_create. However, the device will continue to exist until all han‐
dles to the device have been closed.
The vnd_close function relinquishes the vnd device referenced by the
handle vhp. After a call to vnd_close, the handle is invalidated and
must not be used by the consumer again. The act of calling vnd_close on
a handle does not remove the device. The device is persisted as long as
vnd_unlink has not been called on the device or the containing zone has
not been destroyed.
RETURN VALUES
Upon successful completion, the functions vnd_create and vnd_open
return a pointer to a vnd_handle_t. This handle is used for all subse‐
quent library operations. If either function fails, then a NULL pointer
is returned and more detailed error information is filled into the
integers pointed to by vnderr and syserr. The vnderr and syserr corre‐
spond to the values that would normally be returned by a call to
vnd_errno(3VND) and vnd_syserrno(3VND). For the full list of possible
errors see libvnd(3LIB).
The vnd_unlink function returns zero on success and -1 on failure. On
failure, the vnd and system errnos are updated and available through
the vnd_errno(3VND) and vnd_syserrno(3VND) functions.
The vnd_close function does not return any values nor does it set
vnderr or syserr. The handle passed to vnd_close can no longer be used.
EXAMPLES
Example 1 Creating a device
The following sample C program shows how to create a vnd device over an
existing datalink named "net0" that other applications can open and use
as "vnd0".
#include <libvnd.h>
#include <stdio.h>
int
main(void)
{
vnd_handle_t *vhp;
vnd_errno_t vnderr;
int syserr;
/* Errors are considered fatal */
vhp = vnd_create(NULL, "net0", "vnd0", &vnderr, &syserr);
if (vhp == NULL) {
if (vnderr == VND_E_SYS)
(void) fprintf(stderr, "failed to create device: %s",
vnd_strsyserror(syserr));
else
(void) fprintf(stderr, "failed to create device: %s",
vnd_strerror(vnderr));
return (1);
}
(void) printf("successfully created vnd00);
vnd_close(vhp);
return (0);
}
Example 2 Opening an existing device in another zone
The following sample C program opens the device named "vnd1" in the
zone named "turin" for further use.
#include <libvnd.h>
#include <stdio.h>
int
main(void)
{
vnd_handle_t *vhp;
vnd_errno_t vnderr;
int syserr, ret;
vhp = vnd_open("turin", "vnd1", &vnderr, &syserr);
if (vhp != NULL) {
if (vnderr == VND_E_SYS)
(void) fprintf(stderr, "failed to open device: %s",
vnd_strsyserror(syserr));
else
(void) fprintf(stderr, "failed to open device: %s",
vnd_strerror(vnderr));
return (1);
}
/*
* Use the device vnd1 with the handle vhp with any of
* the other interfaces documented in libvnd(3LIB) here.
*
* After an arbitrary amount of code, the program will
* set the variable ret with the exit code for the
* program and should execute the following code before
* returning.
*/
vnd_close(vhp);
return (ret);
}
Example 3 Removing a device
The following sample C program removes a vnd device named vnd0. This
program makes it so no additional programs can access the device. How‐
ever, if anyone is actively using it, it will still exist, similar to
calling unlink(2).
#include <libvnd.h>
#include <stdio.h>
int
main(void)
{
vnd_handle_t *vhp;
vnd_errno_t vnderr;
int syserr, ret;
vhp = vnd_open(NULL, "vnd0", &vnderr, &syserr);
if (vhp != NULL) {
if (vnderr == VND_E_SYS)
(void) fprintf(stderr, "failed to open device: %s",
vnd_strsyserror(syserr));
else
(void) fprintf(stderr, "failed to open device: %s",
vnd_strerror(vnderr));
return (1);
}
if (vnd_unlink(vhp) != 0) {
if (vnderr == VND_E_SYS)
(void) fprintf(stderr, "failed to unlink device: %s",
vnd_strsyserror(syserr));
else
(void) fprintf(stderr, "failed to unlink device: %s",
vnd_strerror(vnderr));
ret = 1;
} else {
(void) printf("successfully unlinked vnd0!0);
ret = 0;
}
vnd_close(vhp);
return (ret);
}
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌───────────────┬─────────────────────────────────┐
│ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├───────────────┼─────────────────────────────────┤
│Stability │ Committed │
├───────────────┼─────────────────────────────────┤
│MT-Level │ See "THREADING" in libvnd(3LIB) │
└───────────────┴─────────────────────────────────┘
SEE ALSOlibvnd(3LIB), vnd_errno(3VND), vnd_syserrno(3VND), attributes(5), priv‐
ileges(5)
Feb 21, 2014 VND_CREATE(3VND)
