contrib/ofed/librdmacm/man/rdma_getaddrinfo.3

   1 .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md
   2 .TH "RDMA_GETADDRINFO" 3 "2010-07-19" "librdmacm" "Librdmacm Programmer's Manual" librdmacm
   3 .SH NAME
   4 rdma_getaddrinfo \- Provides transport independent address translation.
   5 .SH SYNOPSIS
   6 .B "#include <rdma/rdma_cma.h>"
   7 .P
   8 .B "int" rdma_getaddrinfo
   9 .BI "(const char *" node ","
  10 .BI "const char *" service ","
  11 .BI "const struct rdma_addrinfo *" hints ","
  12 .BI "struct rdma_addrinfo **" res ");"
  13 .SH ARGUMENTS
  14 .IP "node" 12
  15 Optional, name, dotted-decimal IPv4, or IPv6 hex address to resolve.
  16 .IP "service" 12
  17 Service name or port number of address.
  18 .IP "hints" 12
  19 Reference to an rdma_addrinfo structure containing hints about the type
  20 of service the caller supports.
  21 .IP "res" 12
  22 A pointer to a linked list of rdma_addrinfo structures containing response
  23 information.
  24 .SH "DESCRIPTION"
  25 Resolves the destination node and service address and returns
  26 information needed to establish communication.  Provides the
  27 RDMA functional equivalent to getaddrinfo.
  28 .SH "RETURN VALUE"
  29 Returns 0 on success, or -1 on error.  If an error occurs, errno will be
  30 set to indicate the failure reason.
  31 .SH "NOTES"
  32 Either node, service, or hints must be provided.  If hints are provided, the
  33 operation will be controlled by hints.ai_flags.  If RAI_PASSIVE is
  34 specified, the call will resolve address information for use on the
  35 passive side of a connection.
  36 If node is provided, rdma_getaddrinfo will attempt to resolve the RDMA address,
  37 route, and connection data to the given node.  The hints parameter, if provided,
  38 may be used to control the resulting output as indicated below.
  39 If node is not given, rdma_getaddrinfo will attempt to resolve the RDMA addressing
  40 information based on the hints.ai_src_addr, hints.ai_dst_addr, or hints.ai_route.
  41 .SH "rdma_addrinfo"
  42 .IP "ai_flags" 12
  43 Hint flags that control the operation.  Supported flags are:
  44 .IP "RAI_PASSIVE" 12
  45 Indicates that the results will be used on the passive/listening
  46 side of a connection.
  47 .IP "RAI_NUMERICHOST" 12
  48 If specified, then the node parameter, if provided, must be a numerical
  49 network address.  This flag suppresses any lengthy address resolution.
  50 .IP "RAI_NOROUTE" 12
  51 If set, this flag suppresses any lengthy route resolution.
  52 .IP "RAI_FAMILY" 12
  53 If set, the ai_family setting should be used as an input hint for interpretting
  54 the node parameter.
  55 .IP "ai_family" 12
  56 Address family for the source and destination address.  Supported families
  57 are: AF_INET, AF_INET6, and AF_IB.
  58 .IP "ai_qp_type" 12
  59 Indicates the type of RDMA QP used for communication.  Supported types are:
  60 IBV_UD (unreliable datagram) and IBV_RC (reliable connected).
  61 .IP "ai_port_space" 12
  62 RDMA port space in use.  Supported values are: RDMA_PS_UDP, RDMA_PS_TCP,
  63 and RDMA_PS_IB.
  64 .IP "ai_src_len" 12
  65 The length of the source address referenced by ai_src_addr.  This will be 0
  66 if an appropriate source address could not be discovered for a given
  67 destination.
  68 .IP "ai_dst_len" 12
  69 The length of the destination address referenced by ai_dst_addr.  This
  70 will be 0 if the RAI_PASSIVE flag was specified as part of the hints.
  71 .IP "ai_src_addr" 12
  72 If provided, the address for the local RDMA device.
  73 .IP "ai_dst_addr" 12
  74 If provided, the address for the destination RDMA device.
  75 .IP "ai_src_canonname" 12
  76 The canonical for the source.
  77 .IP "ai_dst_canonname" 12
  78 The canonical for the destination.
  79 .IP "ai_route_len" 12
  80 Size of the routing information buffer referenced by ai_route.  This will
  81 be 0 if the underlying transport does not require routing data, or none
  82 could be resolved.
  83 .IP "ai_route" 12
  84 Routing information for RDMA transports that require routing data as part
  85 of connection establishment.  The format of the routing data depends on
  86 the underlying transport.  If Infiniband transports are
  87 used, ai_route will reference an array of struct ibv_path_data on output,
  88 if routing data is available.  Routing paths may be restricted by setting
  89 desired routing data fields on input to rdma_getaddrinfo.  For Infiniband,
  90 hints.ai_route may reference an array of struct ibv_path_record or
  91 struct ibv_path_data on input.
  92 .IP "ai_connect_len" 12
  93 Size of connection information referenced by ai_connect.  This will be
  94 0 if the underlying transport does not require additional connection
  95 information.
  96 .IP "ai_connect" 12
  97 Data exchanged as part of the connection establishment process.  If provided,
  98 ai_connect data must be transferred as private data, with any user supplied
  99 private data following it.
 100 .IP "ai_next" 12
 101 Pointer to the next rdma_addrinfo structure in the list.  Will be NULL
 102 if no more structures exist.
 103 .SH "SEE ALSO"
 104 rdma_create_id(3), rdma_resolve_route(3), rdma_connect(3), rdma_create_qp(3),
 105 rdma_bind_addr(3), rdma_create_ep(3)