'\" te .\" 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] .TH DLPI_OPEN 3DLPI "Nov 17, 2008" .SH NAME dlpi_open \- open DLPI link .SH SYNOPSIS .LP .nf \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ldlpi\fR [ \fIlibrary\fR ... ] #include <libdlpi.h> \fBint\fR \fBdlpi_open\fR(\fBconst char *\fR\fIlinkname\fR, \fBdlpi_handle_t *\fR\fIdhp\fR, \fBuint_t\fR \fIflags\fR); .fi .SH DESCRIPTION .sp .LP The \fBdlpi_open()\fR function creates an open instance of the \fBDLPI\fR Version 2 link named by \fIlinkname\fR and associates it with a dynamically-allocated \fBdlpi_handle_t\fR, which is returned to the caller in \fIdhp\fR upon success. The \fBDLPI\fR handle is left in the \fBDL_UNBOUND\fR \fBDLPI\fR state after a successful open of the \fBDLPI\fR 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 \fBDL_STYLE1\fR and \fBDL_STYLE2\fR \fBDLPI\fR links. .sp .LP By default (if \fBDLPI_DEVIPNET\fR is not set in \fIflags\fR), the \fBdlpi_open()\fR function scans the \fB/dev/net\fR and \fB/dev\fR directories for DLPI links, in order. Within each scanned directory, \fBdlpi_open()\fR first looks for a matching \fBDL_STYLE1\fR link, then for a matching \fBDL_STYLE2\fR link. If \fIprovider\fR is considered the \fIlinkname\fR with its trailing digits removed, a matching \fBDL_STYLE1\fR link has a filename of \fIlinkname\fR, and a matching \fBDL_STYLE2\fR link has a filename of \fIprovider\fR. If a \fBDL_STYLE2\fR link is opened, \fBdlpi_open()\fR automatically performs the necessary \fBDLPI\fR operations to place the \fBDLPI\fR link instance and the associated \fBDLPI\fR handle in the \fBDL_UNBOUND\fR state. See \fBdlpi\fR(7P) for the definition of \fIlinkname\fR. .sp .LP If \fBDLPI_DEVIPNET\fR is set in \fIflags\fR, \fBdlpi_open()\fR opens the file \fIlinkname\fR in \fB/dev/ipnet\fR as a \fBDL_STYLE1\fR DLPI device and does not look in any other directories. .sp .LP The value of \fIflags\fR is constructed by a bitwise-inclusive-OR of the flags listed below, defined in \fB<libdlpi.h>\fR. .sp .ne 2 .na \fB\fBDLPI_DEVIPNET\fR\fR .ad .RS 18n Specify that the named DLPI device is an IP observability device (see \fBipnet\fR(7D)), and \fBdl_open()\fR will open the device from the \fB/dev/ipnet/\fR directory. .RE .sp .ne 2 .na \fB\fBDLPI_IPNETINFO\fR\fR .ad .RS 18n This flag is applicable only when opening IP Observability devices (with \fBDLPI_DEVIPNET\fR or by opening the \fB/dev/lo0\fR device). This flag causes the \fBipnet\fR driver to prepend an \fBipnet\fR header to each received IP packet. See \fBipnet\fR(7D) for the contents of this header. .RE .sp .ne 2 .na \fB\fBDLPI_NATIVE\fR\fR .ad .RS 18n Enable \fBDLPI\fR native mode (see \fBDLIOCNATIVE\fR in \fBdlpi\fR(7P)) on a \fBDLPI\fR link instance. Native mode persists until the \fBDLPI\fR handle is closed by \fBdlpi_close\fR(3DLPI). .RE .sp .ne 2 .na \fB\fBDLPI_PASSIVE\fR\fR .ad .RS 18n Enable \fBDLPI\fR passive mode (see \fBDL_PASSIVE_REQ\fR in \fBdlpi\fR(7P)) on a \fBDLPI\fR link instance. Passive mode persists until the \fBDLPI\fR handle is closed by \fBdlpi_close\fR(3DLPI). .RE .sp .ne 2 .na \fB\fBDLPI_RAW\fR\fR .ad .RS 18n Enable \fBDLPI\fR raw mode (see \fBDLIOCRAW\fR in \fBdlpi\fR(7P)) on a \fBDLPI\fR link instance. Raw mode persists until the \fBDLPI\fR handle is closed by \fBdlpi_close\fR(3DLPI). .RE .sp .LP Each \fBDLPI\fR handle has an associated timeout value that is used as a timeout interval for certain \fBlibdlpi\fR operations. The default timeout value ensures that \fBDLPI_ETIMEDOUT\fR is returned from a \fBlibdlpi\fR operation only in the event that the \fBDLPI\fR link becomes unresponsive. The timeout value can be changed with \fBdlpi_set_timeout\fR(3DLPI), although this should seldom be necessary. .SH RETURN VALUES .sp .LP Upon success, \fBDLPI_SUCCESS\fR is returned. If \fBDL_SYSERR\fR is returned, \fBerrno\fR contains the specific UNIX system error value. Otherwise, a \fBDLPI\fR error value defined in \fB<sys/dlpi.h>\fR or listed in the following section is returned. .SH ERRORS .sp .LP The \fBdlpi_open()\fR function will fail if: .sp .ne 2 .na \fB\fBDLPI_EBADLINK\fR\fR .ad .RS 25n Bad \fBDLPI\fR link .RE .sp .ne 2 .na \fB\fBDLPI_EIPNETINFONOTSUP\fR\fR .ad .RS 25n The \fBDLPI_IPNETINFO\fR flag was set but the device opened does not support the \fBDLIOCIPNETINFO\fR ioctl. .RE .sp .ne 2 .na \fB\fBDLPI_ELINKNAMEINVAL\fR\fR .ad .RS 25n Invalid \fBDLPI\fR \fIlinkname\fR .RE .sp .ne 2 .na \fB\fBDLPI_ENOLINK\fR\fR .ad .RS 25n \fBDLPI\fR link does not exist .RE .sp .ne 2 .na \fB\fBDLPI_ERAWNOTSUP\fR\fR .ad .RS 25n DLPI raw mode not supported .RE .sp .ne 2 .na \fB\fBDLPI_ETIMEDOUT\fR\fR .ad .RS 25n \fBDLPI\fR operation timed out .RE .sp .ne 2 .na \fB\fBDLPI_FAILURE\fR\fR .ad .RS 25n DLPI operation failed .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for description of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Committed _ MT-Level Safe .TE .SH SEE ALSO .sp .LP \fBdlpi_close\fR(3DLPI), \fBdlpi_set_timeout\fR(3DLPI), \fBlibdlpi\fR(3LIB), \fBattributes\fR(5), \fBdlpi\fR(7P), \fBipnet\fR(7D)