Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
cc [ flag ... ] file ... -ldlpi [ library ... ] #include <libdlpi.h> int dlpi_open(const char *linkname, dlpi_handle_t *dhp, uint_t flags);
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.
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.
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
See attributes(5) for description of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Interface Stability | Committed |
| MT-Level | Safe |
dlpi_close(3DLPI), dlpi_set_timeout(3DLPI), libdlpi(3LIB), attributes(5), dlpi(7P), ipnet(7D)