--- name: "rdma_get_cm_event" section: "3" platform: "linux" package: "rdma-core" version: "65.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/rdma_get_cm_event" --- # rdma\_get\_cm\_event(3) Retrieves the next pending communication event. ## NAME rdma\_get\_cm\_event - Retrieves the next pending communication event. ## SYNOPSIS **#include \** **int rdma\_get\_cm\_event** **(struct rdma\_event\_channel \****channel***,** **struct rdma\_cm\_event \*\****event***);** ## ARGUMENTS - channel Event channel to check for events. - event Allocated information about the next communication event. ## DESCRIPTION Retrieves a communication event. If no events are pending, by default, the call will block until an event is received. ## RETURN VALUE Returns 0 on success, or -1 on error. If an error occurs, errno will be set to indicate the failure reason. ## NOTES The default synchronous behavior of this routine can be changed by modifying the file descriptor associated with the given channel. All events that are reported must be acknowledged by calling rdma\_ack\_cm\_event. Destruction of an rdma\_cm\_id will block until related events have been acknowledged. ## EVENT DATA Communication event details are returned in the rdma\_cm\_event structure. This structure is allocated by the rdma\_cm and released by the rdma\_ack\_cm\_event routine. Details of the rdma\_cm\_event structure are given below. - id The rdma\_cm identifier associated with the event. If the event type is RDMA\_CM\_EVENT\_CONNECT\_REQUEST, then this references a new id for that communication. - listen\_id For RDMA\_CM\_EVENT\_CONNECT\_REQUEST event types, this references the corresponding listening request identifier. - event Specifies the type of communication event which occurred. See EVENT TYPES below. - status Returns any asynchronous error information associated with an event. The status is zero if the operation was successful, otherwise the status value is non-zero and is either set to a negative errno or a transport specific value. For details on transport specific status values, see the event type information below. - param Provides additional details based on the type of event. Users should select the conn or ud subfields based on the rdma\_port\_space of the rdma\_cm\_id associated with the event. See UD EVENT DATA and CONN EVENT DATA below. ## UD EVENT DATA Event parameters related to unreliable datagram (UD) services: RDMA\_PS\_UDP and RDMA\_PS\_IPOIB. The UD event data is valid for RDMA\_CM\_EVENT\_ESTABLISHED and RDMA\_CM\_EVENT\_MULTICAST\_JOIN events, unless stated otherwise. - private\_data References any user-specified data associated with RDMA\_CM\_EVENT\_CONNECT\_REQUEST or RDMA\_CM\_EVENT\_ESTABLISHED events. The data referenced by this field matches that specified by the remote side when calling rdma\_connect or rdma\_accept. This field is NULL if the event does not include private data. The buffer referenced by this pointer is deallocated when calling rdma\_ack\_cm\_event. - private\_data\_len The size of the private data buffer. Users should note that the size of the private data buffer may be larger than the amount of private data sent by the remote side. Any additional space in the buffer will be zeroed out. - ah\_attr Address information needed to send data to the remote endpoint(s). Users should use this structure when allocating their address handle. - qp\_num QP number of the remote endpoint or multicast group. - qkey QKey needed to send data to the remote endpoint(s). ## CONN EVENT DATA Event parameters related to connected QP services: RDMA\_PS\_TCP. The connection related event data is valid for RDMA\_CM\_EVENT\_CONNECT\_REQUEST and RDMA\_CM\_EVENT\_ESTABLISHED events, unless stated otherwise. - private\_data References any user-specified data associated with the event. The data referenced by this field matches that specified by the remote side when calling rdma\_connect or rdma\_accept. This field is NULL if the event does not include private data. The buffer referenced by this pointer is deallocated when calling rdma\_ack\_cm\_event. - private\_data\_len The size of the private data buffer. Users should note that the size of the private data buffer may be larger than the amount of private data sent by the remote side. Any additional space in the buffer will be zeroed out. - responder\_resources The number of responder resources requested of the recipient. This field matches the initiator depth specified by the remote node when calling rdma\_connect and rdma\_accept. - initiator\_depth The maximum number of outstanding RDMA read/atomic operations that the recipient may have outstanding. This field matches the responder resources specified by the remote node when calling rdma\_connect and rdma\_accept. - flow\_control Indicates if hardware level flow control is provided by the sender. - retry\_count For RDMA\_CM\_EVENT\_CONNECT\_REQUEST events only, indicates the number of times that the recipient should retry send operations. - rnr\_retry\_count The number of times that the recipient should retry receiver not ready (RNR) NACK errors. - srq Specifies if the sender is using a shared-receive queue. - qp\_num Indicates the remote QP number for the connection. ## EVENT TYPES The following types of communication events may be reported. - RDMA\_CM\_EVENT\_ADDR\_RESOLVED Address resolution (rdma\_resolve\_addr) completed successfully. - RDMA\_CM\_EVENT\_ADDR\_ERROR Address resolution (rdma\_resolve\_addr) failed. - RDMA\_CM\_EVENT\_ROUTE\_RESOLVED Route resolution (rdma\_resolve\_route) completed successfully. - RDMA\_CM\_EVENT\_ROUTE\_ERROR Route resolution (rdma\_resolve\_route) failed. - RDMA\_CM\_EVENT\_CONNECT\_REQUEST Generated on the passive side to notify the user of a new connection request. - RDMA\_CM\_EVENT\_CONNECT\_RESPONSE Generated on the active side to notify the user of a successful response to a connection request. It is only generated on rdma\_cm\_id's that do not have a QP associated with them. - RDMA\_CM\_EVENT\_CONNECT\_ERROR Indicates that an error has occurred trying to establish or a connection. May be generated on the active or passive side of a connection. - RDMA\_CM\_EVENT\_UNREACHABLE Generated on the active side to notify the user that the remote server is not reachable or unable to respond to a connection request. If this event is generated in response to a UD QP resolution request over InfiniBand, the event status field will contain an errno, if negative, or the status result carried in the IB CM SIDR REP message. - RDMA\_CM\_EVENT\_REJECTED Indicates that a connection request or response was rejected by the remote end point. The event status field will contain the transport specific reject reason if available. Under InfiniBand, this is the reject reason carried in the IB CM REJ message. - RDMA\_CM\_EVENT\_ESTABLISHED Indicates that a connection has been established with the remote end point. - RDMA\_CM\_EVENT\_DISCONNECTED The connection has been disconnected. - RDMA\_CM\_EVENT\_DEVICE\_REMOVAL The local RDMA device associated with the rdma\_cm\_id has been removed. Upon receiving this event, the user must destroy the related rdma\_cm\_id. - RDMA\_CM\_EVENT\_MULTICAST\_JOIN The multicast join operation (rdma\_join\_multicast) completed successfully. - RDMA\_CM\_EVENT\_MULTICAST\_ERROR An error either occurred joining a multicast group, or, if the group had already been joined, on an existing group. The specified multicast group is no longer accessible and should be rejoined, if desired. - RDMA\_CM\_EVENT\_ADDR\_CHANGE The network device associated with this ID through address resolution changed its HW address, eg following of bonding failover. This event can serve as a hint for applications who want the links used for their RDMA sessions to align with the network stack. - RDMA\_CM\_EVENT\_TIMEWAIT\_EXIT The QP associated with a connection has exited its timewait state and is now ready to be re-used. After a QP has been disconnected, it is maintained in a timewait state to allow any in flight packets to exit the network. After the timewait state has completed, the rdma\_cm will report this event. - RDMA\_CM\_EVENT\_ADDRINFO\_RESOLVED Address information resolution (rdma\_resolve\_addrinfo) completed successfully. - RDMA\_CM\_EVENT\_ADDRINFO\_ERROR Address information resolution (rdma\_resolve\_addrinfo) failed. - RDMA\_CM\_EVENT\_USER This allows a user-defined event to be written to the RDMA CM event channel. Event details are specified by the user and not interpreted by the librdmacm. This event is useful for a multi-threaded application to signal a thread which may be waiting on the RDMA CM event channel. ## SEE ALSO [rdma\_ack\_cm\_event(3)](/rdma_ack_cm_event/3.md), [rdma\_create\_event\_channel(3)](/rdma_create_event_channel/3.md), [rdma\_resolve\_addr(3)](/rdma_resolve_addr/3.md), [rdma\_resolve\_route(3)](/rdma_resolve_route/3.md), [rdma\_connect(3)](/rdma_connect/3.md), [rdma\_listen(3)](/rdma_listen/3.md), [rdma\_join\_multicast(3)](/rdma_join_multicast/3.md), [rdma\_destroy\_id(3)](/rdma_destroy_id/3.md), [rdma\_event\_str(3)](/rdma_event_str/3.md),[rdma\_write\_cm\_event(3)](/rdma_write_cm_event/3.md)