| Current File : //usr/man/man3dlpi/dlpi_info.3dlpi |
'\" te
.\" Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
.TH dlpi_info 3DLPI "15 Apr 2011" "SunOS 5.11" "Data Link Provider Interface Library Functions"
.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 \fIversion\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 \fIversion\fR argument specifies the version of the \fBdlpi_info_t\fR structure expected by the caller. Callers can use the macro \fBDLPI_INFO_VERSION\fR to specify the default version, which is currently 0. Callers can request version 1 of the \fBdlpi_info_t\fR structure by defining \fBDLPI_INFO_VERSION\fR to 1 before including \fB<libdlpi.h>\fR and passing the defined \fBDLPI_INFO_VERSION\fR value of 1 as the version argument. See the description of \fIdi_linkname\fR below for the difference between version 0 and 1.
.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
.mk
.na
\fB\fIdi_opts\fR\fR
.ad
.sp .6
.RS 4n
Reserved for future \fBdlpi_info_t\fR expansion.
.RE
.sp
.ne 2
.mk
.na
\fB\fIdi_max_sdu\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fIdi_min_sdu\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fIdi_state\fR\fR
.ad
.sp .6
.RS 4n
Current \fBDLPI\fR state of \fIdh\fR; either \fBDL_UNBOUND\fR or \fBDL_IDLE\fR.
.RE
.sp
.ne 2
.mk
.na
\fB\fIdi_mactype\fR\fR
.ad
.sp .6
.RS 4n
\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
.mk
.na
\fB\fIdi_linkname\fR\fR
.ad
.sp .6
.RS 4n
Link name associated with \fBDLPI\fR handle \fIdh\fR. If the caller specifies the default \fIversion\fR argument value of 0, the size of this field is \fBDLPI_LINKNAME_MAX\fR. If the caller defines \fBDLPI_INFO_VERSION\fR to value 1 before including \fB<libdlpi.h>\fR, the size of this field is MAXLINKNAMESPECIFIER. See \fBdlpi\fR(7P) for information on link names and the supported maximum length of DLPI link names.
.RE
.sp
.ne 2
.mk
.na
\fB\fIdi_physaddr\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fIdi_physaddrlen\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fIdi_bcastaddr\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fIdi_bcastaddrlen\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fIdi_sap\fR\fR
.ad
.sp .6
.RS 4n
\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
.mk
.na
\fB\fIdi_timeout\fR\fR
.ad
.sp .6
.RS 4n
Current timeout value, in seconds, set on the \fBdlpi\fR handle.
.RE
.sp
.ne 2
.mk
.na
\fB\fIdi_qos_sel\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fIdi_qos_range\fR\fR
.ad
.sp .6
.RS 4n
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
.mk
.na
\fB\fBDLPI_EBADMSG\fR\fR
.ad
.RS 20n
.rt
Bad DLPI message
.RE
.sp
.ne 2
.mk
.na
\fB\fBDLPI_EINHANDLE\fR\fR
.ad
.RS 20n
.rt
Invalid \fBDLPI\fR handle
.RE
.sp
.ne 2
.mk
.na
\fB\fBDLPI_EINVAL\fR\fR
.ad
.RS 20n
.rt
Invalid argument
.RE
.sp
.ne 2
.mk
.na
\fB\fBDLPI_EMODENOTSUP\fR\fR
.ad
.RS 20n
.rt
Unsupported \fBDLPI\fR connection mode
.RE
.sp
.ne 2
.mk
.na
\fB\fBDLPI_ETIMEDOUT\fR\fR
.ad
.RS 20n
.rt
\fBDLPI\fR operation timed out
.RE
.sp
.ne 2
.mk
.na
\fB\fBDLPI_EVERNOTSUP\fR\fR
.ad
.RS 20n
.rt
Unsupported \fBDLPI\fR Version
.RE
.sp
.ne 2
.mk
.na
\fB\fBDLPI_FAILURE\fR\fR
.ad
.RS 20n
.rt
\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(5) for description of the following attributes:
.sp
.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i)
lw(2.75i) |lw(2.75i)
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE
.SH SEE ALSO
.sp
.LP
\fBdlpi_bind\fR(3DLPI), \fBlibdlpi\fR(3LIB), \fBattributes\fR(5), \fBdlpi\fR(7P)