| .\" -*- nroff -*- |
| .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md |
| .\" |
| .TH UMAD_RECV 3 "May 11, 2007" "OpenIB" "OpenIB Programmer's Manual" |
| .SH "NAME" |
| umad_recv \- receive umad |
| .SH "SYNOPSIS" |
| .nf |
| .B #include <infiniband/umad.h> |
| .sp |
| .BI "int umad_recv(int " "portid" ", void " "*umad" ", int " "*length" ", int " "timeout_ms"); |
| .fi |
| .SH "DESCRIPTION" |
| .B umad_recv() |
| waits up to |
| .I timeout_ms\fR |
| milliseconds for an incoming MAD message to be received from the port specified by |
| .I portid\fR. |
| |
| A MAD "message" consists of a single MAD packet |
| .I or |
| a coalesced multipacket RMPP transmission. In the RMPP case the header of the |
| first RMPP packet is returned as the header of the buffer and the buffer data |
| contains the coalesced data section of each subsequent RMPP MAD packet within |
| the transmission. Thus all the RMPP headers except the first are not copied to |
| user space from the kernel. |
| |
| The message is copied to the |
| .I umad\fR |
| buffer if there is sufficient room and the received |
| .I length\fR is indicated. |
| If the buffer is not large enough, the size of the umad |
| buffer needed is returned in |
| .I length\fR. |
| A negative |
| .I timeout_ms\fR |
| makes the function block until a packet is received. A |
| .I timeout_ms\fR |
| parameter of zero indicates a non blocking read. |
| |
| .B Note |
| .I length |
| is a pointer to the length of the |
| .B data |
| portion of the umad buffer. This means that |
| .I umad |
| must point to a buffer at least umad_size() + |
| .I *length |
| bytes long. |
| |
| .B Note also |
| that |
| .I *length\fR |
| must be >= 256 bytes. This length allows for at least a single MAD packet to |
| be returned. |
| |
| .SH "RETURN VALUE" |
| .B umad_recv() |
| on success return the agentid; on error, errno is set and a negative value is |
| returned as follows: |
| -EINVAL invalid port handle or agentid or *length is less than the minimum supported |
| -EIO receive operation failed |
| -EWOULDBLOCK non blocking read can't be fulfilled |
| -ENOSPC The provided buffer is not long enough for the complete message. |
| .SH "SEE ALSO" |
| .BR umad_poll (3) |
| .SH "AUTHOR" |
| .TP |
| Hal Rosenstock <halr@voltaire.com> |
