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);


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(7P) 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(7D)), 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(7D) for the contents of this header.


DLPI_NATIVE
Enable DLPI native mode (see DLIOCNATIVE in dlpi(7P))
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(7P)) 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(7P)) 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.

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() 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


ATTRIBUTES


See attributes(5) for description of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+

SEE ALSO


dlpi_close(3DLPI), dlpi_set_timeout(3DLPI), libdlpi(3LIB), attributes(5),
dlpi(7P), ipnet(7D)


November 17, 2008 DLPI_OPEN(3DLPI)