| .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md |
| .TH "RDMA_GETADDRINFO" 3 "2010-07-19" "librdmacm" "Librdmacm Programmer's Manual" librdmacm |
| .SH NAME |
| rdma_getaddrinfo \- Provides transport independent address translation. |
| .SH SYNOPSIS |
| .B "#include <rdma/rdma_cma.h>" |
| .P |
| .B "int" rdma_getaddrinfo |
| .BI "(const char *" node "," |
| .BI "const char *" service "," |
| .BI "const struct rdma_addrinfo *" hints "," |
| .BI "struct rdma_addrinfo **" res ");" |
| .SH ARGUMENTS |
| .IP "node" 12 |
| Optional, name, dotted-decimal IPv4, or IPv6 hex address to resolve. |
| .IP "service" 12 |
| Service name or port number of address. |
| .IP "hints" 12 |
| Reference to an rdma_addrinfo structure containing hints about the type |
| of service the caller supports. |
| .IP "res" 12 |
| A pointer to a linked list of rdma_addrinfo structures containing response |
| information. |
| .SH "DESCRIPTION" |
| Resolves the destination node and service address and returns |
| information needed to establish communication. Provides the |
| RDMA functional equivalent to getaddrinfo. |
| .SH "RETURN VALUE" |
| Returns 0 on success, or -1 on error (errno will be set to indicate the failure |
| reason), or one of the following nonzero error codes: |
| .IP "EAI_ADDRFAMILY" 12 |
| The specified network host does not have any network addresses in the |
| requested address family. |
| .IP "EAI_AGAIN" 12 |
| The name server returned a temporary failure indication. Try again later. |
| .IP "EAI_BADFLAGS" 12 |
| hints.ai_flags contains invalid flags. |
| .IP "EAI_FAIL" 12 |
| The name server returned a permanent failure indication. |
| .IP "EAI_FAMILY" 12 |
| The requested address family is not supported. |
| .IP "EAI_MEMORY" 12 |
| Out of memory. |
| .IP "EAI_NODATA" 12 |
| The specified network host exists, but does not have any network addresses |
| defined. |
| .IP "EAI_NONAME" 12 |
| The node or service is not known; or both node and service are NULL. |
| .IP "EAI_SERVICE" 12 |
| The requested service is not available for the requested QP type. It may be |
| available through another QP type. |
| .IP "EAI_QPTYPE" 12 |
| The requested socket type is not supported. This could occur, for example, |
| if hints.ai_qptype and hints.ai_port_space are inconsistent (e.g., IBV_QPT_UD |
| and RDMA_PS_TCP, respectively). |
| .IP "EAI_SYSTEM" 12 |
| Other system error, check errno for details. |
| The gai_strerror() function translates these error codes to a human readable |
| string, suitable for error reporting. |
| .SH "NOTES" |
| Either node, service, or hints must be provided. If hints are provided, the |
| operation will be controlled by hints.ai_flags. If RAI_PASSIVE is |
| specified, the call will resolve address information for use on the |
| passive side of a connection. |
| If node is provided, rdma_getaddrinfo will attempt to resolve the RDMA address, |
| route, and connection data to the given node. The hints parameter, if provided, |
| may be used to control the resulting output as indicated below. |
| If node is not given, rdma_getaddrinfo will attempt to resolve the RDMA addressing |
| information based on the hints.ai_src_addr, hints.ai_dst_addr, or hints.ai_route. |
| .SH "rdma_addrinfo" |
| .IP "ai_flags" 12 |
| Hint flags that control the operation. Supported flags are: |
| .IP "RAI_PASSIVE" 12 |
| Indicates that the results will be used on the passive/listening |
| side of a connection. |
| .IP "RAI_NUMERICHOST" 12 |
| If specified, then the node parameter, if provided, must be a numerical |
| network address. This flag suppresses any lengthy address resolution. |
| .IP "RAI_NOROUTE" 12 |
| If set, this flag suppresses any lengthy route resolution. |
| .IP "RAI_FAMILY" 12 |
| If set, the ai_family setting should be used as an input hint for interpretting |
| the node parameter. |
| .IP "ai_family" 12 |
| Address family for the source and destination address. Supported families |
| are: AF_INET, AF_INET6, and AF_IB. |
| .IP "ai_qp_type" 12 |
| Indicates the type of RDMA QP used for communication. Supported types are: |
| IBV_QPT_UD (unreliable datagram) and IBV_QPT_RC (reliable connected). |
| .IP "ai_port_space" 12 |
| RDMA port space in use. Supported values are: RDMA_PS_UDP, RDMA_PS_TCP, |
| and RDMA_PS_IB. |
| .IP "ai_src_len" 12 |
| The length of the source address referenced by ai_src_addr. This will be 0 |
| if an appropriate source address could not be discovered for a given |
| destination. |
| .IP "ai_dst_len" 12 |
| The length of the destination address referenced by ai_dst_addr. This |
| will be 0 if the RAI_PASSIVE flag was specified as part of the hints. |
| .IP "ai_src_addr" 12 |
| If provided, the address for the local RDMA device. |
| .IP "ai_dst_addr" 12 |
| If provided, the address for the destination RDMA device. |
| .IP "ai_src_canonname" 12 |
| The canonical for the source. |
| .IP "ai_dst_canonname" 12 |
| The canonical for the destination. |
| .IP "ai_route_len" 12 |
| Size of the routing information buffer referenced by ai_route. This will |
| be 0 if the underlying transport does not require routing data, or none |
| could be resolved. |
| .IP "ai_route" 12 |
| Routing information for RDMA transports that require routing data as part |
| of connection establishment. The format of the routing data depends on |
| the underlying transport. If Infiniband transports are |
| used, ai_route will reference an array of struct ibv_path_data on output, |
| if routing data is available. Routing paths may be restricted by setting |
| desired routing data fields on input to rdma_getaddrinfo. For Infiniband, |
| hints.ai_route may reference an array of struct ibv_path_record or |
| struct ibv_path_data on input. |
| .IP "ai_connect_len" 12 |
| Size of connection information referenced by ai_connect. This will be |
| 0 if the underlying transport does not require additional connection |
| information. |
| .IP "ai_connect" 12 |
| Data exchanged as part of the connection establishment process. If provided, |
| ai_connect data must be transferred as private data, with any user supplied |
| private data following it. |
| .IP "ai_next" 12 |
| Pointer to the next rdma_addrinfo structure in the list. Will be NULL |
| if no more structures exist. |
| .SH "SEE ALSO" |
| rdma_create_id(3), rdma_resolve_route(3), rdma_connect(3), rdma_create_qp(3), |
| rdma_bind_addr(3), rdma_create_ep(3), rdma_freeaddrinfo(3) |
