illumos: manual page: libvnd.3lib

LIBVND(3LIB) Interface Libraries 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
interfaces. 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 properties
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 buffer.
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
successfully.

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_create
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
acknowledgement.

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
different 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 minimum
buffer size. This generally occurs when making the
buffer size less than the maximum transmission
unit.

28 VND_E_DLEXCL
unable to obtain exclusive access to dlpi link,
link busy

When a vnd device is created, it expects exclusive
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 capability. As
such, the data path could not be initialized.

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 writeable,
see the section above entitled "PROPERTIES".

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_strsyserror. 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_handle_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 caller'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