LIBVND(3LIB)LIBVND(3LIB)NAME
libvnd - vnd library
SYNOPSIS
cc [ flag... ] file... -lvnd [ library... ]
#include <libvnd.h>
DESCRIPTION
The libvnd library provides a stable and programmatic interface to
vnd(7D) devices. vnd devices provide the means for creating a layer two
interface over a data link, similar to the use of libdlpi(3LIB) and
IP(7P). In dlpi parlance, a vnd device obtains data from all service
attachment points (SAP). For ethernet devices, this means that a vnd
device sends and receives traffic for all ethertypes. It is intended to
be used for services such as virtual machines which emulate layer two
devices.
Handles to vnd(7D) devices are obtained through the use of vnd_create
and vnd_open. With a handle, I/O can be performed and properties on the
device can be set and retrieved. I/O on devices should be performed
through the vnd_frameio_read and vnd_frameio_write functions. A file
descriptor suitable for use with event ports and polling may be
obtained through vnd_pollfd. Handles are relinquished through calls to
vnd_close; however, devices will persist until vnd_unlink has been
called.
The rest of this manual documents the interfaces, properties, errors,
and threading model for libvnd. The in-depth description of individual
interfaces, their arguments, and examples, are in manual pages for each
provided interface.
INTERFACES
The shared object libvnd.so.1 provides the public interfaces defined
below. See Intro(3) for additional information on shared object inter‐
faces. Individual functions are documented in their own manual pages.
vnd_create vnd_errno
vnd_open vnd_syserrno
vnd_unlink vnd_strerror
vnd_close vnd_strsyserror
vnd_pollfd vnd_walk
vnd_prop_get vnd_prop_set
vnd_prop_iter vnd_prop_writeable
vnd_frameio_read vnd_frameio_write
PROPERTIES
The following table summarizes properties of a vnd device. The proper‐
ties can be retrieved and set with the functions vnd_prop_get(3VND) and
vnd_prop_set(3VND). Following the table, the structures and properties
are described in greater detail.
+-------------------+---------------------+-------+
| PROPERTY | STRUCTURE | PERM |
+-------------------+---------------------+-------+
| VND_PROP_RXBUF | vnd_prop_buf_t | R/W |
+-------------------+---------------------+-------+
| VND_PROP_TXBUF | vnd_prop_buf_t | R/W |
+-------------------+---------------------+-------+
| VND_PROP_MAXBUF | vnd_prop_buf_t | R/- |
+-------------------+---------------------+-------+
| VND_PROP_MINTU | vnd_prop_buf_t | R/- |
+-------------------+---------------------+-------+
| VND_PROP_MAXTU | vnd_prop_buf_t | R/- |
+-------------------+---------------------+-------+
Structures
The vnd_prop_buf_t structure has the following members:
uint64_t vpb_size;
The vpb_size member refers to a size in bytes. When getting a property,
it represents the size of that property, when setting a property, it is
the size to set the property to.
Property Descriptions
rxbuf
A read/write property that controls the size of the receive buffer
for the device. All received data enters the receive buffer until a
consumer consumes it. If adding a received frame would exceed the
size of the receive buffer, then that frame will be dropped. The
maximum size of the buffer is limited by the 'maxsize' property.
txbuf
A read/write property that controls the size of the transmit buf‐
fer. All in-flight transmitted data must be able to fix into the
transmit buffer to deal with potential flow control events. If
there is not enough space in the transmit buffer, transmit related
I/O operations will either block or fail based on whether or not
O_NONBLOCK or O_NDELAY were set with fcntl(2).
maxsize
A read only property that describes the maximum size of buffers in
the system. Properties such as rxbuf and txbuf cannot be set beyond
this.
mintu
A read only property that describes the minimum size of a frame
transmitted to the underlying data link. Note that the minimum
listed here may be less than the size of a valid layer two frame
and therefore may be dropped. A frame smaller than this value will
be rejected by vnd.
maxtu
A read only property that describes the maximum size of a frame
transmitted to the underlying data link. A frame larger than this
value will be rejected by vnd.
ERRORS
Most interfaces provided by libvnd provide a means to retrieve a
vnd_errno_t that describes an error that has occurred. The manuals for
individual interfaces describe whether or not this additional error
information is available and how to retrieve it. The following is a
complete list of the error numbers and their names as defined in
<sys/vnd_errno.h>. Any entries not listed here are private to the
implementation and may change at any time.
0 VND_E_SUCCESS
no error
This indicates that the operation completed suc‐
cessfully.
1 VND_E_NOMEM
not enough memory available
Insufficient memory was available. This is the
equivalent of the standard system errno ENOMEM.
2 VND_E_NODATALINK
no such datalink
The data link requested to be used as part of
vnd_create does not exist in the requested zone.
3 VND_E_NOTETHER
datalink not of type DL_ETHER
The data link used as part of a call to vnd_cre‐
ate is not an Ethernet device. vnd_create only
works with Ethernet devices at this time.
4 VND_E_DLPIINVAL
unknown dlpi failure
An unexpected DLPI message was received during
vnd device initialization.
5 VND_E_ATTACHFAIL
DL_ATTACH_REQ failed
During vnd device initialization, the dlpi call
to attach to the requested data link failed.
6 VND_E_BINDFAIL
DL_BIND_REQ failed
During vnd device initialization, the dlpi call
to bind to a service attachment point on the
data link failed.
7 VND_E_PROMISCFAIL
DL_PROMISCON_REQ failed
During vnd device initialization, the dlpi call
to enable promiscuous mode on the underlying
device failed.
8 VND_E_DIRECTFAIL
DLD_CAPAB_DIRECT enable failed
During vnd device initialization, the dlpi call
to enable the DLD fast path failed.
9 VND_E_CAPACKINVAL
bad datalink capability
During vnd device initialization, the kernel
responded with an invalid capability acknowl‐
edgement.
10 VND_E_SUBCAPINVAL
bad datalink subcapability
During vnd device initialization, the kernel
responded with an invalid sub-capability.
11 VND_E_DLDBADVERS
bad dld version
The vnd(7D) module does not support the version
of the dld capability that the kernel sent. As
such, the data path could not be brought up and
the device could not be fully initialized.
12 VND_E_KSTATCREATE
failed to create kstats
During vnd device initialization, the necessary
kstats could not be created.
13 VND_E_NODEV
no such vnd link
During device initialization, the requested
character device did not exist.
14 VND_E_NONETSTACK
netstack doesn't exist
During device initialization, the networking
stack for the device did not exist.
15 VND_E_ASSOCIATED
device already associated
During vnd device initialization, the vnd
STREAMS device was already associated with
another vnd device.
16 VND_E_ATTACHED
device already attached
The given vnd device has already been created
over a data link and cannot be created over
another one.
17 VND_E_LINKED
device already linked
The given vnd device has already been given a
name and bound into the file system name space.
18 VND_E_BADNAME
invalid name
The requested name is not a valid name. Valid
names are alphanumeric ascii names, along with
the following ascii characters: ':', '-', and
´_'. Names must be less than LIBVND_NAMELEN
bytes including the null terminator.
19 VND_E_PERM
permission denied
A request was made from a non-global zone to
manipulate a vnd device that belongs to a dif‐
ferent zone.
20 VND_E_NOZONE
no such zone
A request was made which targeted a zone that
did not exist.
21 VND_E_STRINIT
failed to initialize vnd stream module
During vnd device initialization, the vnd
STREAMS module could not be pushed onto the data
link's stream head.
22 VND_E_NOTATTACHED
device not attached
A request was made that requires a vnd device be
attached to a data link, such as a call to
change a property. The device was not attached
to a data link.
23 VND_E_NOTLINKED
device not linked
A request was made to a vnd device that requires
the vnd device to be named and present in /dev.
The given device was not linked into /dev at the
time of the call.
24 VND_E_LINKEXISTS
another device has the same link name
When trying to link a given vnd device into a
zones /dev name space, another device already
exists with the same name.
25 VND_E_MINORNODE
failed to create minor node
While trying to link a vnd device into the
/devices and /dev name space, the call to
ddi_create_minor_node() failed.
26 VND_E_BUFTOOBIG
requested buffer size is too large
The requested buffer size exceeds the maximum
valid value for the given property.
27 VND_E_BUFTOOSMALL
requested buffer size is too small
The requested buffer size is less than the mini‐
mum buffer size. This generally occurs when mak‐
ing the buffer size less than the maximum trans‐
mission unit.
28 VND_E_DLEXCL
unable to obtain exclusive access to dlpi link,
link busy
When a vnd device is created, it expects exclu‐
sive active access to the device. If any other
active dlpi consumers, such as IP, are already
using the device, then the vnd device will not
be created. Passive consumers, such as snoop,
can still use a device that has been exclusively
opened.
28 VND_E_DIRECTNOTSUP
DLD direct capability not supported over data
link
The data link that the vnd device was created
over does not supported the DLD Direct capabil‐
ity. As such, the data path could not be ini‐
tialized.
30 VND_E_BADPROPSIZE
invalid property size
The size of the data passed into vnd_prop_get or
vnd_prop_set is incorrect and does not match the
expected data size.
31 VND_E_BADPROP
invalid property
An unknown property identifier was specified.
For a list of valid properties, see the section
above entitled "PROPERTIES".
32 VND_E_PROPRDONLY
property is read only
An operation tried to update the value of a read
only property. For a list of which properties
are read only and which are readable and write‐
able, see the section above entitled "PROPER‐
TIES".
33 VND_E_SYS
unexpected system error
This indicates that there is no vnd specific
error available and that the system errno is
valid. The system errno can be obtained and
printed through vnd_syserrno and vnd_strsyser‐
ror. The possible values and their meanings are
documented in Intro(2).
34 VND_E_CAPABPASS
capabilities invalid, pass-through module
detected
While negotiating capabilities, a pass-through
module was detected and the capability had to be
discarded. Because of this, the data path could
not be initialized.
THREADING
The libvnd library is not truly MT-safe. MT-safety is provided on the
granularity of a given vnd_handle_t. Operations on a single vnd_han‐
dle_t are unsafe; however, operations on different handles are MT-safe.
If a single vnd_handle_t is used by multiple threads, it is the call‐
er's responsibility to provide locking to ensure that multiple threads
aren't simultaneously calling into libvnd on a single handle.
FILES
/usr/lib/libvnd.so.1
shared object
/usr/lib/64/libvnd.so.1
64-bit shared object
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌───────────────┬─────────────────┐
│ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├───────────────┼─────────────────┤
│Stability │ Committed │
├───────────────┼─────────────────┤
│MT-Level │ See "THREADING" │
└───────────────┴─────────────────┘
SEE ALSOattributes(5), Intro(2), fcntl(2), Intro(3), fcntl.h(3HEAD), lib‐
dlpi(3LIB), port_create(3C), vnd(7D)vnd_close(3VND), vnd_create(3VND), vnd_errno(3VND),
vnd_frameio_read(3VND), vnd_frameio_write(3VND), vnd_open(3VND)vnd_pollfd(3VND), vnd_prop_get(3VND), vnd_prop_iter(3VND),
vnd_prop_set(3VND), vnd_prop_writeable(3VND), vnd_walk(3VND)
Mar 06, 2014 LIBVND(3LIB)