libvnd man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

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 ALSO
       attributes(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)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net