--- name: "fi_cm" section: "3" platform: "linux" package: "libfabric" version: "2.7.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/fi_cm" --- # fi\_cm(3) Connection management operations ## NAME fi\_cm - Connection management operations - fi\_connect / fi\_listen / fi\_accept / fi\_reject / fi\_shutdown Manage endpoint connection state. - fi\_setname / fi\_getname / fi\_getpeer Set local, or return local or peer endpoint address. - fi\_join / fi\_close / fi\_mc\_addr Join, leave, or retrieve a multicast address. ## SYNOPSIS - ``` #include int fi_connect(struct fid_ep *ep, const void *addr, const void *param, size_t paramlen); int fi_listen(struct fid_pep *pep); int fi_accept(struct fid_ep *ep, const void *param, size_t paramlen); int fi_reject(struct fid_pep *pep, fid_t handle, const void *param, size_t paramlen); int fi_shutdown(struct fid_ep *ep, uint64_t flags); int fi_setname(fid_t fid, void *addr, size_t addrlen); int fi_getname(fid_t fid, void *addr, size_t *addrlen); int fi_getpeer(struct fid_ep *ep, void *addr, size_t *addrlen); int fi_join(struct fid_ep *ep, const void *addr, uint64_t flags, struct fid_mc **mc, void *context); int fi_close(struct fid *mc); fi_addr_t fi_mc_addr(struct fid_mc *mc); ``` ## ARGUMENTS - *ep / pep* Fabric endpoint on which to change connection state. *fid* Active or passive endpoint to get/set address. - *addr* Buffer to address. On a set call, the endpoint will be assigned the specified address. On a get, the local address will be copied into the buffer, up to the space provided. For connect, this parameter indicates the peer address to connect to. The address must be in the same format as that specified using fi\_info: addr\_format when the endpoint was created. - *addrlen* On input, specifies size of addr buffer. On output, stores number of bytes written to addr buffer. - *param* User-specified data exchanged as part of the connection exchange. - *paramlen* Size of param buffer. - *info* Fabric information associated with a connection request. - *mc* Multicast group associated with an endpoint. - *flags* Additional flags for controlling connection operation. - *context* User context associated with the request. ## DESCRIPTION Connection management functions are used to connect an connection-oriented (FI\_EP\_MSG) endpoint to a listening peer. ### fi\_listen The fi\_listen call indicates that the specified endpoint should be transitioned into a passive connection state, allowing it to accept incoming connection requests. Connection requests against a listening endpoint are reported asynchronously to the user through a bound CM event queue using the FI\_CONNREQ event type. The number of outstanding connection requests that can be queued at an endpoint is limited by the listening endpoint’s backlog parameter. The backlog is initialized based on administrative configuration values, but may be adjusted through the fi\_control call. ### fi\_connect The fi\_connect call initiates a connection request on a connection-oriented endpoint to the destination address. fi\_connect may only be called on an endpoint once in its lifetime. ### fi\_accept / fi\_reject The fi\_accept and fi\_reject calls are used on the passive (listening) side of a connection to accept or reject a connection request, respectively. To accept a connection, the listening application first waits for a connection request event (FI\_CONNREQ). After receiving such an event, the application allocates a new endpoint to accept the connection. This endpoint must be allocated using an fi\_info structure referencing the handle from this FI\_CONNREQ event. fi\_accept is then invoked with the newly allocated endpoint. If the listening application wishes to reject a connection request, it calls fi\_reject with the listening endpoint and a reference to the connection request. A successfully accepted connection request will result in the active (connecting) endpoint seeing an FI\_CONNECTED event on its associated event queue. A rejected or failed connection request will generate an error event. The error entry will provide additional details describing the reason for the failed attempt. An FI\_CONNECTED event will also be generated on the passive side for the accepting endpoint once the connection has been properly established. The fid of the FI\_CONNECTED event will be that of the endpoint passed to fi\_accept as opposed to the listening passive endpoint. Outbound data transfers cannot be initiated on a connection-oriented endpoint until an FI\_CONNECTED event has been generated. However, receive buffers may be associated with an endpoint anytime. ### fi\_shutdown The fi\_shutdown call is used to gracefully disconnect an endpoint from its peer. The flags parameter is reserved and must be 0. Outstanding operations posted to the endpoint when fi\_shutdown is called will be canceled or discarded. Notification of canceled operations will be reported by the provider to the corresponding completion queue(s). Discarded operations will silently be dropped, with no completions generated. The choice of canceling, versus discarding operations, is provider dependent. However, all canceled completions will be written before fi\_shutdown returns. When called, fi\_shutdown does not affect completions already written to a completion queue. Any queued completions associated with asynchronous operations posted to the endpoint may still be retrieved from the corresponding completion queue(s) after an endpoint has been shutdown. An FI\_SHUTDOWN event will be generated for an endpoint when the remote peer issues a disconnect using fi\_shutdown or abruptly closes the endpoint. Note that in the abrupt close case, an FI\_SHUTDOWN event will only be generated if the peer system is reachable and a service or kernel agent on the peer system is able to notify the local endpoint that the connection has been aborted. ### fi\_close Fi\_close is used to disassociate an endpoint from a multicast group and close all resources associated with the group. Fi\_close must be called on all multicast groups that an endpoint joins. ### fi\_setname The fi\_setname call may be used to modify or assign the address of the local endpoint. It is conceptually similar to the socket bind operation. An endpoint may be assigned an address on its creation, through the fi\_info structure. The fi\_setname call allows an endpoint to be created without being associated with a specific service (e.g., port number) and/or node (e.g., network) address, with the addressing assigned dynamically. The format of the specified addressing data must match that specified through the fi\_info structure when the endpoint was created. If no service address is specified and a service address has not yet been assigned to the endpoint, then the provider will allocate a service address and assign it to the endpoint. If a node or service address is specified, then, upon successful completion of fi\_setname, the endpoint will be assigned the given addressing. If an address cannot be assigned, or the endpoint address cannot be modified, an appropriate fabric error number is returned. ### fi\_getname / fi\_getpeer The fi\_getname and fi\_getpeer calls may be used to retrieve the local or peer endpoint address, respectively. On input, the addrlen parameter should indicate the size of the addr buffer. If the actual address is larger than what can fit into the buffer, it will be truncated and -FI\_ETOOSMALL will be returned. On output, addrlen is set to the size of the buffer needed to store the address, which may be larger than the input value. fi\_getname is not guaranteed to return a valid source address until after the specified endpoint has been enabled or has had an address assigned. An endpoint may be enabled explicitly through fi\_enable, or implicitly, such as through fi\_connect or fi\_listen. An address may be assigned using fi\_setname. fi\_getpeer is not guaranteed to return a valid peer address until an endpoint has been completely connected – an FI\_CONNECTED event has been generated. ### fi\_join This call attaches an endpoint to a multicast group. By default, the endpoint will join the group based on the data transfer capabilities of the endpoint. For example, if the endpoint has been configured to both send and receive data, then the endpoint will be able to initiate and receive transfers to and from the multicast group. The fi\_join flags may be used to restrict access to the multicast group, subject to endpoint capability limitations. Multicast join operations complete asynchronously. An endpoint must be bound to an event queue prior to calling fi\_join. The result of the join operation will be reported to the EQ as an FI\_JOIN\_COMPLETE event. Applications cannot issue multicast transfers until receiving notification that the join operation has completed. Note that an endpoint may begin receiving messages from the multicast group as soon as the join completes, which can occur prior to the FI\_JOIN\_COMPLETE event being generated. Applications must call fi\_close on the multicast group to disconnect the endpoint from the group. After a join operation has completed, the fi\_mc\_addr call may be used to retrieve the address associated with the multicast group. ### fi\_mc\_addr Returns the fi\_addr\_t address associated with a multicast group. This address must be used when transmitting data to a multicast group and paired with the FI\_MULTICAST operation flag. ## FLAGS Except in functions noted below, flags are reserved and must be 0. - *FI\_SEND* Applies to fi\_join. This flag indicates that the endpoint should join the multicast group as a send only member. The endpoint must be configured for transmit operations to use this flag, or an error will occur. - *FI\_RECV* Applies to fi\_join. This flag indicates that the endpoint should join the multicast group with receive permissions only. The endpoint must be configured for receive operations to use this flag, or an error will occur. ## RETURN VALUE Returns 0 on success. On error, a negative value corresponding to fabric errno is returned. Fabric errno values are defined in rdma/fi\_errno.h. ## ERRORS ## NOTES For connection-oriented endpoints, the buffer referenced by param will be sent as part of the connection request or response, subject to the constraints of the underlying connection protocol. Applications may use fi\_getopt with the FI\_OPT\_CM\_DATA\_SIZE endpoint option to determine the size of application data that may be exchanged as part of a connection request or response. The fi\_connect, fi\_accept, and fi\_reject calls will silently truncate any application data which cannot fit into underlying protocol messages. User data exchanged as part of the connection process is available as part of the fi\_eq\_cm\_entry structure, for FI\_CONNREQ and FI\_CONNECTED events, or as additional err\_data to fi\_eq\_err\_entry, in the case of a rejected connection. ## SEE ALSO [fi\_getinfo(3)](/fi_getinfo/3.md), [fi\_endpoint(3)](/fi_endpoint/3.md), [fi\_domain(3)](/fi_domain/3.md), [fi\_eq(3)](/fi_eq/3.md) ## AUTHORS OpenFabrics.