NAME

       umad_recv - receive umad

SYNOPSIS

       #include <infiniband/umad.h>

       int umad_recv(int portid, void *umad, int *length, int timeout_ms);

DESCRIPTION

       umad_recv() waits up to timeout_ms milliseconds for an incoming MAD message to be received
       from the port specified by portid.

       A MAD "message"  consists  of  a  single  MAD  packet  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 umad buffer if there is  sufficient  room  and  the  received
       length  is  indicated.   If  the  buffer  is not large enough, the size of the umad buffer
       needed is returned in length.  A negative timeout_ms makes  the  function  block  until  a
       packet is received. A timeout_ms parameter of zero indicates a non blocking read.

       Note length is a pointer to the length of the data portion of the umad buffer.  This means
       that umad must point to a buffer at least umad_size() + *length bytes long.

       Note also that *length must be >= 256 bytes.  This length allows for at least a single MAD
       packet to be returned.

RETURN VALUE

       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.

SEE ALSO

       umad_poll(3)

AUTHOR

       Hal Rosenstock <halr@voltaire.com>