share/man/man3dlpi/dlpi_info.3dlpi

   1 '\" te
   2 .\"  Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DLPI_INFO 3DLPI "Aug 22, 2007"
   7 .SH NAME
   8 dlpi_info \- get DLPI information
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ldlpi\fR [ \fIlibrary\fR ... ]
  13 #include <libdlpi.h>
  14
  15 \fBint\fR \fIdlpi_info\fR(\fBdlpi_handle_t\fR \fIdh\fR, \fBdlpi_info_t *\fR\fIinfop\fR,
  16      \fBuint_t\fR \fIopt\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBdlpi_info()\fR function provides \fBDLPI\fR information about the open
  23 \fBDLPI\fR link instance associated with \fBDLPI\fR handle \fIdh\fR. \fBDLPI\fR
  24 information can be retrieved in any state of \fIdh\fR, but some of the
  25 information might not be available if \fIdh\fR is in the \fBDL_UNBOUND\fR
  26 \fBDLPI\fR state. The \fBDLPI\fR information received is copied into
  27 \fIinfop\fR, which must point to a \fBdlpi_info_t\fR allocated by the caller.
  28 The \fIopt\fR argument is reserved for future use and must be set to 0.
  29 .sp
  30 .LP
  31 The \fBdlpi_info_t\fR is a structure defined in \fB<libdlpi.h>\fR as follows:
  32 .sp
  33 .in +2
  34 .nf
  35 typedef struct {
  36      uint_t                  di_opts;
  37      uint_t                  di_max_sdu;
  38      uint_t                  di_min_sdu;
  39      uint_t                  di_state;
  40      uchar_t                 di_mactype;
  41      char                    di_linkname[DLPI_LINKNAME_MAX];
  42      uchar_t                 di_physaddr[DLPI_PHYSADDR_MAX];
  43      uchar_t                 di_physaddrlen;
  44      uchar_t                 di_bcastaddr[DLPI_PHYSADDR_MAX];
  45      uchar_t                 di_bcastaddrlen;
  46      uint_t                  di_sap;
  47      int                     di_timeout;
  48      dl_qos_cl_sel1_t        di_qos_sel;
  49      dl_qos_cl_range1_t      di_qos_range;
  50 } dlpi_info_t;
  51 .fi
  52 .in -2
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIdi_opts\fR\fR
  58 .ad
  59 .RS 19n
  60 Reserved for future \fBdlpi_info_t\fR expansion.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIdi_max_sdu\fR\fR
  67 .ad
  68 .RS 19n
  69 Maximum message size, in bytes, that the \fBDLPI\fR link is able to accept for
  70 transmission. The value is guaranteed to be greater than or equal to
  71 \fIdi_min_sdu\fR.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIdi_min_sdu\fR\fR
  78 .ad
  79 .RS 19n
  80 Minimum message size, in bytes, that the \fBDLPI\fR link is able to accept for
  81 transmission. The value is guaranteed to be greater than or equal to one.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIdi_state\fR\fR
  88 .ad
  89 .RS 19n
  90 Current \fBDLPI\fR state of \fIdh\fR; either \fBDL_UNBOUND\fR or \fBDL_IDLE\fR.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fIdi_mactype\fR\fR
  97 .ad
  98 .RS 19n
  99 \fBMAC\fR type supported by the \fBDLPI\fR link associated with \fIdh\fR. See
 100 \fB<sys/dlpi.h>\fR for the list of possible \fBMAC\fR types.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIdi_linkname\fR\fR
 107 .ad
 108 .RS 19n
 109 Link name associated with \fBDLPI\fR handle \fIdh\fR.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fIdi_physaddr\fR\fR
 116 .ad
 117 .RS 19n
 118 Link-layer physical address of bound \fIdh\fR. If \fIdh\fR is in the
 119 \fBDL_UNBOUND\fR \fBDLPI\fR state, the contents of \fIdi_physaddr\fR are
 120 unspecified.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fIdi_physaddrlen\fR\fR
 127 .ad
 128 .RS 19n
 129 Physical address length, in bytes. If \fIdh\fR is in the \fBDL_UNBOUND\fR
 130 \fBDLPI\fR state, \fIdi_physaddrlen\fR is set to zero.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fIdi_bcastaddr\fR\fR
 137 .ad
 138 .RS 19n
 139 Link-layer broadcast address. If the \fIdi_mactype\fR of the \fBDLPI\fR link
 140 does not support broadcast, the contents of \fIdi_bcastaddr\fR are unspecified.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fIdi_bcastaddrlen\fR\fR
 147 .ad
 148 .RS 19n
 149 Link-layer broadcast address length, in bytes. If the \fIdi_mactype\fR of the
 150 \fBDLPI\fR link does not support broadcast, \fIdi_bcastaddrlen\fR is set to
 151 zero.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fIdi_sap\fR\fR
 158 .ad
 159 .RS 19n
 160 \fBSAP\fR currently bound to handle. If \fIdh\fR is in the \fBDL_UNBOUND\fR
 161 \fBDLPI\fR state, \fIdi_sap\fR is set to zero.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fIdi_timeout\fR\fR
 168 .ad
 169 .RS 19n
 170 Current timeout value, in seconds, set on the \fBdlpi\fR handle.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fIdi_qos_sel\fR\fR
 177 .ad
 178 .RS 19n
 179 Current \fBQOS\fR parameters supported by the \fBDLPI\fR link instance
 180 associated with \fIdh\fR. Unsupported \fBQOS\fR parameters are set to
 181 \fBDL_UNKNOWN\fR.
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fIdi_qos_range\fR\fR
 188 .ad
 189 .RS 19n
 190 Available range of \fBQOS\fR parameters supported by a \fBDLPI\fR link instance
 191 associated with the \fBDLPI\fR handle \fIdh\fR. Unsupported \fBQOS\fR range
 192 values are set to \fBDL_UNKNOWN\fR.
 193 .RE
 194
 195 .SH RETURN VALUES
 196 .sp
 197 .LP
 198 Upon success, \fBDLPI_SUCCESS\fR is returned. If \fBDL_SYSERR\fR is returned,
 199 \fBerrno\fR contains the specific UNIX system error value. Otherwise, a
 200 \fBDLPI\fR error value defined in \fB<sys/dlpi.h>\fR or an error value listed
 201 in the following section is returned.
 202 .SH ERRORS
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBDLPI_EBADMSG\fR\fR
 207 .ad
 208 .RS 20n
 209 Bad DLPI message
 210 .RE
 211
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBDLPI_EINHANDLE\fR\fR
 216 .ad
 217 .RS 20n
 218 Invalid \fBDLPI\fR handle
 219 .RE
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBDLPI_EINVAL\fR\fR
 225 .ad
 226 .RS 20n
 227 Invalid argument
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBDLPI_EMODENOTSUP\fR\fR
 234 .ad
 235 .RS 20n
 236 Unsupported \fBDLPI\fR connection mode
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fBDLPI_ETIMEDOUT\fR\fR
 243 .ad
 244 .RS 20n
 245 \fBDLPI\fR operation timed out
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fBDLPI_EVERNOTSUP\fR\fR
 252 .ad
 253 .RS 20n
 254 Unsupported \fBDLPI\fR Version
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fBDLPI_FAILURE\fR\fR
 261 .ad
 262 .RS 20n
 263 \fBDLPI\fR operation failed
 264 .RE
 265
 266 .SH EXAMPLES
 267 .LP
 268 \fBExample 1 \fRGet link-layer broadcast address
 269 .sp
 270 .LP
 271 The following example shows how \fBdlpi_info()\fR can be used.
 272
 273 .sp
 274 .in +2
 275 .nf
 276 #include <libdlpi.h>
 277
 278 uchar_t *
 279 get_bcastaddr(const char *linkname, uchar_t *baddrlenp)
 280 {
 281         dlpi_handle_t   dh;
 282         dlpi_info_t     dlinfo;
 283         uchar_t         *baddr;
 284
 285         if (dlpi_open(linkname, &dh, 0) != DLPI_SUCCESS)
 286                 return (NULL);
 287
 288         if (dlpi_info(dh, &dlinfo, 0) != DLPI_SUCCESS) {
 289                 dlpi_close(dh);
 290                 return (NULL);
 291         }
 292         dlpi_close(dh);
 293
 294         *baddrlenp = dlinfo.di_bcastaddrlen;
 295         if ((baddr = malloc(*baddrlenp)) == NULL)
 296                 return (NULL);
 297
 298         return (memcpy(baddr, dlinfo.di_bcastaddr, *baddrlenp));
 299 }
 300 .fi
 301 .in -2
 302
 303 .SH ATTRIBUTES
 304 .sp
 305 .LP
 306 See \fBattributes\fR(5) for description of the following attributes:
 307 .sp
 308
 309 .sp
 310 .TS
 311 box;
 312 c | c
 313 l | l .
 314 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 315 _
 316 Interface Stability     Committed
 317 _
 318 MT-Level        Safe
 319 .TE
 320
 321 .SH SEE ALSO
 322 .sp
 323 .LP
 324 \fBdlpi_bind\fR(3DLPI), \fBlibdlpi\fR(3LIB), \fBattributes\fR(5)