path: root/usr/src/man/man3dlpi/dlpi_info.3dlpi

'\" te
.\"  Copyright (c) 2007, 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_INFO 3DLPI "Aug 22, 2007"
.SH NAME
dlpi_info \- get DLPI information
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ldlpi\fR [ \fIlibrary\fR ... ]
#include <libdlpi.h>

\fBint\fR \fIdlpi_info\fR(\fBdlpi_handle_t\fR \fIdh\fR, \fBdlpi_info_t *\fR\fIinfop\fR,
     \fBuint_t\fR \fIopt\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBdlpi_info()\fR function provides \fBDLPI\fR information about the open
\fBDLPI\fR link instance associated with \fBDLPI\fR handle \fIdh\fR. \fBDLPI\fR
information can be retrieved in any state of \fIdh\fR, but some of the
information might not be available if \fIdh\fR is in the \fBDL_UNBOUND\fR
\fBDLPI\fR state. The \fBDLPI\fR information received is copied into
\fIinfop\fR, which must point to a \fBdlpi_info_t\fR allocated by the caller.
The \fIopt\fR argument is reserved for future use and must be set to 0.
.sp
.LP
The \fBdlpi_info_t\fR is a structure defined in \fB<libdlpi.h>\fR as follows:
.sp
.in +2
.nf
typedef struct {
     uint_t                  di_opts;
     uint_t                  di_max_sdu;
     uint_t                  di_min_sdu;
     uint_t                  di_state;
     uchar_t                 di_mactype;
     char                    di_linkname[DLPI_LINKNAME_MAX];
     uchar_t                 di_physaddr[DLPI_PHYSADDR_MAX];
     uchar_t                 di_physaddrlen;
     uchar_t                 di_bcastaddr[DLPI_PHYSADDR_MAX];
     uchar_t                 di_bcastaddrlen;
     uint_t                  di_sap;
     int                     di_timeout;
     dl_qos_cl_sel1_t        di_qos_sel;
     dl_qos_cl_range1_t      di_qos_range;
} dlpi_info_t;
.fi
.in -2

.sp
.ne 2
.na
\fB\fIdi_opts\fR\fR
.ad
.RS 19n
Reserved for future \fBdlpi_info_t\fR expansion.
.RE

.sp
.ne 2
.na
\fB\fIdi_max_sdu\fR\fR
.ad
.RS 19n
Maximum message size, in bytes, that the \fBDLPI\fR link is able to accept for
transmission. The value is guaranteed to be greater than or equal to
\fIdi_min_sdu\fR.
.RE

.sp
.ne 2
.na
\fB\fIdi_min_sdu\fR\fR
.ad
.RS 19n
Minimum message size, in bytes, that the \fBDLPI\fR link is able to accept for
transmission. The value is guaranteed to be greater than or equal to one.
.RE

.sp
.ne 2
.na
\fB\fIdi_state\fR\fR
.ad
.RS 19n
Current \fBDLPI\fR state of \fIdh\fR; either \fBDL_UNBOUND\fR or \fBDL_IDLE\fR.
.RE

.sp
.ne 2
.na
\fB\fIdi_mactype\fR\fR
.ad
.RS 19n
\fBMAC\fR type supported by the \fBDLPI\fR link associated with \fIdh\fR. See
\fB<sys/dlpi.h>\fR for the list of possible \fBMAC\fR types.
.RE

.sp
.ne 2
.na
\fB\fIdi_linkname\fR\fR
.ad
.RS 19n
Link name associated with \fBDLPI\fR handle \fIdh\fR.
.RE

.sp
.ne 2
.na
\fB\fIdi_physaddr\fR\fR
.ad
.RS 19n
Link-layer physical address of bound \fIdh\fR. If \fIdh\fR is in the
\fBDL_UNBOUND\fR \fBDLPI\fR state, the contents of \fIdi_physaddr\fR are
unspecified.
.RE

.sp
.ne 2
.na
\fB\fIdi_physaddrlen\fR\fR
.ad
.RS 19n
Physical address length, in bytes. If \fIdh\fR is in the \fBDL_UNBOUND\fR
\fBDLPI\fR state, \fIdi_physaddrlen\fR is set to zero.
.RE

.sp
.ne 2
.na
\fB\fIdi_bcastaddr\fR\fR
.ad
.RS 19n
Link-layer broadcast address. If the \fIdi_mactype\fR of the \fBDLPI\fR link
does not support broadcast, the contents of \fIdi_bcastaddr\fR are unspecified.
.RE

.sp
.ne 2
.na
\fB\fIdi_bcastaddrlen\fR\fR
.ad
.RS 19n
Link-layer broadcast address length, in bytes. If the \fIdi_mactype\fR of the
\fBDLPI\fR link does not support broadcast, \fIdi_bcastaddrlen\fR is set to
zero.
.RE

.sp
.ne 2
.na
\fB\fIdi_sap\fR\fR
.ad
.RS 19n
\fBSAP\fR currently bound to handle. If \fIdh\fR is in the \fBDL_UNBOUND\fR
\fBDLPI\fR state, \fIdi_sap\fR is set to zero.
.RE

.sp
.ne 2
.na
\fB\fIdi_timeout\fR\fR
.ad
.RS 19n
Current timeout value, in seconds, set on the \fBdlpi\fR handle.
.RE

.sp
.ne 2
.na
\fB\fIdi_qos_sel\fR\fR
.ad
.RS 19n
Current \fBQOS\fR parameters supported by the \fBDLPI\fR link instance
associated with \fIdh\fR. Unsupported \fBQOS\fR parameters are set to
\fBDL_UNKNOWN\fR.
.RE

.sp
.ne 2
.na
\fB\fIdi_qos_range\fR\fR
.ad
.RS 19n
Available range of \fBQOS\fR parameters supported by a \fBDLPI\fR link instance
associated with the \fBDLPI\fR handle \fIdh\fR. Unsupported \fBQOS\fR range
values are set to \fBDL_UNKNOWN\fR.
.RE

.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 an error value listed
in the following section is returned.
.SH ERRORS
.sp
.ne 2
.na
\fB\fBDLPI_EBADMSG\fR\fR
.ad
.RS 20n
Bad DLPI message
.RE

.sp
.ne 2
.na
\fB\fBDLPI_EINHANDLE\fR\fR
.ad
.RS 20n
Invalid \fBDLPI\fR handle
.RE

.sp
.ne 2
.na
\fB\fBDLPI_EINVAL\fR\fR
.ad
.RS 20n
Invalid argument
.RE

.sp
.ne 2
.na
\fB\fBDLPI_EMODENOTSUP\fR\fR
.ad
.RS 20n
Unsupported \fBDLPI\fR connection mode
.RE

.sp
.ne 2
.na
\fB\fBDLPI_ETIMEDOUT\fR\fR
.ad
.RS 20n
\fBDLPI\fR operation timed out
.RE

.sp
.ne 2
.na
\fB\fBDLPI_EVERNOTSUP\fR\fR
.ad
.RS 20n
Unsupported \fBDLPI\fR Version
.RE

.sp
.ne 2
.na
\fB\fBDLPI_FAILURE\fR\fR
.ad
.RS 20n
\fBDLPI\fR operation failed
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRGet link-layer broadcast address
.sp
.LP
The following example shows how \fBdlpi_info()\fR can be used.

.sp
.in +2
.nf
#include <libdlpi.h>

uchar_t *
get_bcastaddr(const char *linkname, uchar_t *baddrlenp)
{
        dlpi_handle_t   dh;
        dlpi_info_t     dlinfo;
        uchar_t         *baddr;

        if (dlpi_open(linkname, &dh, 0) != DLPI_SUCCESS)
                return (NULL);

        if (dlpi_info(dh, &dlinfo, 0) != DLPI_SUCCESS) {
                dlpi_close(dh);
                return (NULL);
        }
        dlpi_close(dh);

        *baddrlenp = dlinfo.di_bcastaddrlen;
        if ((baddr = malloc(*baddrlenp)) == NULL)
                return (NULL);

        return (memcpy(baddr, dlinfo.di_bcastaddr, *baddrlenp));
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) 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
.BR dlpi_bind (3DLPI),
.BR libdlpi (3LIB),
.BR attributes (7)