illumos: manual page: dlpi_open

DLPI_OPEN(3DLPI) Data Link Provider Interface Library Functions

NAME

dlpi_open - open DLPI link

SYNOPSIS

cc [ flag ... ] file ... -ldlpi [ library ... ]
#include <libdlpi.h>

int dlpi_open(const char *linkname, dlpi_handle_t *dhp,
uint_t flags);

int dlpi_open_zone(const char *linkname, const char *
zonename, dlpi_handle_t *dhp, uint_t flags);

DESCRIPTION

The dlpi_open() function creates an open instance of the DLPI Version 2
link named by linkname and associates it with a dynamically-allocated
dlpi_handle_t, which is returned to the caller in dhp upon success. The
DLPI handle is left in the DL_UNBOUND DLPI state after a successful open
of the DLPI link. The DLPI handles can only be used by one thread at a
time, but multiple handles can be used by multiple threads. This function
can open both DL_STYLE1 and DL_STYLE2 DLPI links.

By default (if DLPI_DEVIPNET is not set in flags), the dlpi_open()
function scans the /dev/net and /dev directories for DLPI links, in
order. Within each scanned directory, dlpi_open() first looks for a
matching DL_STYLE1 link, then for a matching DL_STYLE2 link. If provider
is considered the linkname with its trailing digits removed, a matching
DL_STYLE1 link has a filename of linkname, and a matching DL_STYLE2 link
has a filename of provider. If a DL_STYLE2 link is opened, dlpi_open()
automatically performs the necessary DLPI operations to place the DLPI
link instance and the associated DLPI handle in the DL_UNBOUND state. See
dlpi(4P) for the definition of linkname.

If DLPI_DEVIPNET is set in flags, dlpi_open() opens the file linkname in
/dev/ipnet as a DL_STYLE1 DLPI device and does not look in any other
directories.

The value of flags is constructed by a bitwise-inclusive-OR of the flags
listed below, defined in <libdlpi.h>.

DLPI_DEVIPNET
Specify that the named DLPI device is an IP
observability device (see ipnet(4D)), and dl_open()
will open the device from the /dev/ipnet/ directory.

DLPI_IPNETINFO
This flag is applicable only when opening IP
Observability devices (with DLPI_DEVIPNET or by opening
the /dev/lo0 device). This flag causes the ipnet driver
to prepend an ipnet header to each received IP packet.
See ipnet(4D) for the contents of this header.

DLPI_NATIVE
Enable DLPI native mode (see DLIOCNATIVE in dlpi(4P))
on a DLPI link instance. Native mode persists until the
DLPI handle is closed by dlpi_close(3DLPI).

DLPI_PASSIVE
Enable DLPI passive mode (see DL_PASSIVE_REQ in
dlpi(4P)) on a DLPI link instance. Passive mode
persists until the DLPI handle is closed by
dlpi_close(3DLPI).

DLPI_RAW
Enable DLPI raw mode (see DLIOCRAW in dlpi(4P)) on a
DLPI link instance. Raw mode persists until the DLPI
handle is closed by dlpi_close(3DLPI).

Each DLPI handle has an associated timeout value that is used as a
timeout interval for certain libdlpi operations. The default timeout
value ensures that DLPI_ETIMEDOUT is returned from a libdlpi operation
only in the event that the DLPI link becomes unresponsive. The timeout
value can be changed with dlpi_set_timeout(3DLPI), although this should
seldom be necessary.

The dlpi_open_zone() function behaves as dlpi_open(), except that it
looks for the link specified by linkname in the specified zone zonename
as opposed to the current zone. This function is only meaningful from the
global zone. Instead of scanning /dev/net, dlpi_open_zone() scans
/dev/net/zone/<zonename> for the data link and /dev/ipnet/zone/<zonename>
when DLPI_DEVIPNET is present in flags. If a NULL or empty string is
passed into dlpi_open_zone(), it will behave as though dlpi_open has been
called.

RETURN VALUES

Upon success, DLPI_SUCCESS is returned. If DL_SYSERR is returned, errno
contains the specific UNIX system error value. Otherwise, a DLPI error
value defined in <sys/dlpi.h> or listed in the following section is
returned.

ERRORS

The dlpi_open() and dlpi_open_zone() function will fail if:

DLPI_EBADLINK
Bad DLPI link

DLPI_EIPNETINFONOTSUP
The DLPI_IPNETINFO flag was set but the device
opened does not support the DLIOCIPNETINFO
ioctl.

DLPI_ELINKNAMEINVAL
Invalid DLPI linkname

DLPI_ENOLINK
DLPI link does not exist

DLPI_ERAWNOTSUP
DLPI raw mode not supported

DLPI_ETIMEDOUT
DLPI operation timed out

DLPI_FAILURE
DLPI operation failed