| .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md | |
| .TH "RDMA_CREATE_EP" 3 "2010-07-19" "librdmacm" "Librdmacm Programmer's Manual" librdmacm | |
| .SH NAME | |
| rdma_create_ep \- Allocate a communication identifier and optional QP. | |
| .SH SYNOPSIS | |
| .B "#include <rdma/rdma_cma.h>" | |
| .P | |
| .B "int" rdma_create_ep | |
| .BI "(struct rdma_cm_id **" id "," | |
| .BI "struct rdma_addrinfo *" res "," | |
| .BI "struct ibv_pd *" pd "," | |
| .BI "struct ibv_qp_init_attr *" qp_init_attr ");" | |
| .SH ARGUMENTS | |
| .IP "id" 12 | |
| A reference where the allocated communication identifier will be | |
| returned. | |
| .IP "res" 12 | |
| Address information associated with the rdma_cm_id returned from | |
| rdma_getaddrinfo. | |
| .IP "pd" 12 | |
| Optional protection domain if a QP is associated with the rdma_cm_id. | |
| .IP "qp_init_attr" 12 | |
| Optional initial QP attributes. | |
| .SH "DESCRIPTION" | |
| Creates an identifier that is used to track communication information. | |
| .SH "RETURN VALUE" | |
| Returns 0 on success, or -1 on error. If an error occurs, errno will be | |
| set to indicate the failure reason. | |
| .SH "NOTES" | |
| After resolving address information using rdma_getaddrinfo, a user | |
| may use this call to allocate an rdma_cm_id based on the results. | |
| .P | |
| If the rdma_cm_id will be used on the active side of a connection, | |
| meaning that res->ai_flags does not have RAI_PASSIVE set, rdma_create_ep | |
| will automatically create a QP on the rdma_cm_id if qp_init_attr is | |
| not NULL. The QP will be associated with the specified protection | |
| domain, if provided, or a default protection domain if not. Users | |
| should see rdma_create_qp for details on the use of the pd and | |
| qp_init_attr parameters. After calling rdma_create_ep, the returned | |
| rdma_cm_id may be connected by calling rdma_connect. The active side | |
| calls rdma_resolve_addr and rdma_resolve_route are not necessary. | |
| .P | |
| If the rdma_cm_id will be used on the passive side of a connection, | |
| indicated by having res->ai_flags RAI_PASSIVE set, this call will save | |
| the provided pd and qp_init_attr parameters. When a new connection | |
| request is retrieved by calling rdma_get_request, the rdma_cm_id | |
| associated with the new connection will automatically be associated | |
| with a QP using the pd and qp_init_attr parameters. After calling | |
| rdma_create_ep, the returned rdma_cm_id may be placed into a listening | |
| state by immediately calling rdma_listen. The passive side call | |
| rdma_bind_addr is not necessary. Connection requests may then be | |
| retrieved by calling rdma_get_request. | |
| .P | |
| The newly created rdma_cm_id will be set to use synchronous operation. | |
| Users that wish asynchronous operation must migrate the rdma_cm_id | |
| to a user created event channel using rdma_migrate_id. | |
| .P | |
| Users must release the created rdma_cm_id by calling rdma_destroy_ep. | |
| .SH "SEE ALSO" | |
| rdma_cm(7), rdma_getaddrinfo(3), rdma_create_event_channel(3), | |
| rdma_connect(3), rdma_listen(3), rdma_destroy_ep(3), rdma_migrate_id(3) |