dlpi_open(3DLPI)				  Data Link Provider Interface Library Functions				  dlpi_open(3DLPI)

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-allo-
       cated 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 suc-
       cessful	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 time-
       out 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)

SunOS 5.11							    17 Nov 2008 						  dlpi_open(3DLPI)