usr/src/man/man3dlpi/dlpi_recv.3dlpi

   1 '\" te
   2 .\"  Copyright (c) 2008, 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_RECV 3DLPI "Aug 22, 2007"
   7 .SH NAME
   8 dlpi_recv \- receive a data message using DLPI
   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 \fBdlpi_recv\fR(\fBdlpi_handle_t\fR \fIdh\fR, \fBvoid *\fR\fIsaddrp\fR,
  16      \fBsize_t *\fR \fIsaddrlenp\fR, \fBvoid *\fR\fImsgbuf\fR, \fBsize_t *\fR\fImsglenp\fR,
  17      \fBint\fR \fImsec\fR, \fBdlpi_recvinfo_t *\fR\fIrecvp\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fBdlpi_recv()\fR function attempts to receive data messages over the
  24 \fBDLPI\fR link instance associated with the \fBDLPI\fR handle \fIdh\fR. If
  25 \fIdh\fR is not in the \fBDL_IDLE\fR \fBDLPI\fR state, the attempt fails. The
  26 caller must ensure that \fImsgbuf\fR is at least \fImsglenp\fR bytes in size.
  27 Upon success, \fImsgbuf\fR contains the data message received, \fImsglenp\fR
  28 contains the number of bytes placed in \fImsgbuf\fR.
  29 .sp
  30 .LP
  31 The caller must ensure that \fIsaddrp\fR is at least \fBDLPI_PHYSADDR_MAX\fR
  32 bytes in size and \fIsaddrlenp\fR must contain the length of \fIsaddrp\fR. Upon
  33 success, \fIsaddrp\fR contains the address of the source sending the data
  34 message and \fIsaddrlenp\fR contains the source address length. If the caller
  35 is not interested in the source address, both \fIsaddrp\fR and \fIsaddrlenp\fR
  36 can be left as \fINULL\fR. If the source address is not available, \fIsaddrp\fR
  37 is not filled in and \fIsaddrlenp\fR is set to zero.
  38 .sp
  39 .LP
  40 The \fIdlpi_recvinfo_t\fR is a structure defined in \fB<libdlpi.h>\fR as
  41 follows:
  42 .sp
  43 .in +2
  44 .nf
  45 typedef struct {
  46         uchar_t         dri_destaddr[DLPI_PHYSADDR_MAX];
  47         uchar_t         dri_destaddrlen;
  48         dlpi_addrtype_t dri_destaddrtype;
  49         size_t          dri_totmsglen;
  50 } dlpi_recvinfo_t;
  51 .fi
  52 .in -2
  53
  54 .sp
  55 .LP
  56 Upon success, if \fIrecvp\fR is not set to \fINULL\fR, \fIdri_destaddr\fR
  57 contains the destination address, \fIdri_destaddrlen\fR contains the
  58 destination address length, and \fIdri_totmsglen\fR contains the total length
  59 of the message received. If the destination address is unicast,
  60 \fIdri_destaddrtype\fR is set to \fBDLPI_ADDRTYPE_UNICAST\fR. Otherwise, it is
  61 set to \fBDLPI_ADDRTYPE_GROUP\fR.
  62 .sp
  63 .LP
  64 The values of \fImsglenp\fR and \fIdri_totmsglen\fR might vary when a message
  65 larger than the size of \fImsgbuf\fR is received. In that case, the caller can
  66 use \fIdri_totmsglen\fR to determine the original total length of the message.
  67 .sp
  68 .LP
  69 If the handle is in raw mode, as described in \fBdlpi_open\fR(3DLPI),
  70 \fImsgbuf\fR starts with the link-layer header. See \fBdlpi\fR(7P). The values
  71 of \fIsaddrp\fR, \fIsaddrlenp\fR, and all the members of \fIdlpi_recvinfo_t\fR
  72 except \fIdri_totmsglen\fR are invalid because the address information is
  73 already included in the link-layer header returned by \fImsgbuf\fR.
  74 .sp
  75 .LP
  76 If no message is received within \fImsec\fR milliseconds, \fBdlpi_recv()\fR
  77 returns \fBDLPI_ETIMEDOUT\fR. If \fImsec\fR is \fB0\fR, \fBdlpi_recv()\fR does
  78 not block. If \fImsec\fR is \fB-1\fR, \fBdlpi_recv()\fR does block until a data
  79 message is received.
  80 .SH RETURN VALUES
  81 .sp
  82 .LP
  83 Upon success, \fBDLPI_SUCCESS\fR is returned. If \fBDL_SYSERR\fR is returned,
  84 \fBerrno\fR contains the specific UNIX system error value. Otherwise, a
  85 \fBDLPI\fR error value defined in \fB<sys/dlpi.h>\fR or an error value listed
  86 in the following section is returned.
  87 .SH ERRORS
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBDLPI_EBADMSG\fR\fR
  92 .ad
  93 .RS 20n
  94 Bad DLPI message
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBDLPI_EINHANDLE\fR\fR
 101 .ad
 102 .RS 20n
 103 Invalid \fBDLPI\fR handle
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBDLPI_EINVAL\fR\fR
 110 .ad
 111 .RS 20n
 112 Invalid argument
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBDLPI_ETIMEDOUT\fR\fR
 119 .ad
 120 .RS 20n
 121 \fBDLPI\fR operation timed out
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBDLPI_EUNAVAILSAP\fR\fR
 128 .ad
 129 .RS 20n
 130 Unavailable \fBDLPI\fR \fBSAP\fR
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBDLPI_FAILURE\fR\fR
 137 .ad
 138 .RS 20n
 139 \fBDLPI\fR operation failed
 140 .RE
 141
 142 .SH ATTRIBUTES
 143 .sp
 144 .LP
 145 See \fBattributes\fR(5) for description of the following attributes:
 146 .sp
 147
 148 .sp
 149 .TS
 150 box;
 151 c | c
 152 l | l .
 153 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 154 _
 155 Interface Stability     Committed
 156 _
 157 MT-Level        Safe
 158 .TE
 159
 160 .SH SEE ALSO
 161 .sp
 162 .LP
 163 \fBdlpi_bind\fR(3DLPI), \fBdlpi_open\fR(3DLPI), \fBlibdlpi\fR(3LIB),
 164 \fBattributes\fR(5), \fBdlpi\fR(7P)