1 2.. _dns: 3 4DNS utility functions 5===================== 6 7libuv provides asynchronous variants of `getaddrinfo` and `getnameinfo`. 8 9 10Data types 11---------- 12 13.. c:type:: uv_getaddrinfo_t 14 15 `getaddrinfo` request type. 16 17.. c:type:: void (*uv_getaddrinfo_cb)(uv_getaddrinfo_t* req, int status, struct addrinfo* res) 18 19 Callback which will be called with the getaddrinfo request result once 20 complete. In case it was cancelled, `status` will have a value of 21 ``UV_ECANCELED``. 22 23.. c:type:: uv_getnameinfo_t 24 25 `getnameinfo` request type. 26 27.. c:type:: void (*uv_getnameinfo_cb)(uv_getnameinfo_t* req, int status, const char* hostname, const char* service) 28 29 Callback which will be called with the getnameinfo request result once 30 complete. In case it was cancelled, `status` will have a value of 31 ``UV_ECANCELED``. 32 33 34Public members 35^^^^^^^^^^^^^^ 36 37.. c:member:: uv_loop_t* uv_getaddrinfo_t.loop 38 39 Loop that started this getaddrinfo request and where completion will be 40 reported. Readonly. 41 42.. c:member:: struct addrinfo* uv_getaddrinfo_t.addrinfo 43 44 Pointer to a `struct addrinfo` containing the result. Must be freed by the user 45 with :c:func:`uv_freeaddrinfo`. 46 47 .. versionchanged:: 1.3.0 the field is declared as public. 48 49.. c:member:: uv_loop_t* uv_getnameinfo_t.loop 50 51 Loop that started this getnameinfo request and where completion will be 52 reported. Readonly. 53 54.. c:member:: char[NI_MAXHOST] uv_getnameinfo_t.host 55 56 Char array containing the resulting host. It's null terminated. 57 58 .. versionchanged:: 1.3.0 the field is declared as public. 59 60.. c:member:: char[NI_MAXSERV] uv_getnameinfo_t.service 61 62 Char array containing the resulting service. It's null terminated. 63 64 .. versionchanged:: 1.3.0 the field is declared as public. 65 66.. seealso:: The :c:type:`uv_req_t` members also apply. 67 68 69API 70--- 71 72.. c:function:: int uv_getaddrinfo(uv_loop_t* loop, uv_getaddrinfo_t* req, uv_getaddrinfo_cb getaddrinfo_cb, const char* node, const char* service, const struct addrinfo* hints) 73 74 Asynchronous :man:`getaddrinfo(3)`. 75 76 Either node or service may be NULL but not both. 77 78 `hints` is a pointer to a struct addrinfo with additional address type 79 constraints, or NULL. Consult `man -s 3 getaddrinfo` for more details. 80 81 Returns 0 on success or an error code < 0 on failure. If successful, the 82 callback will get called sometime in the future with the lookup result, 83 which is either: 84 85 * status == 0, the res argument points to a valid `struct addrinfo`, or 86 * status < 0, the res argument is NULL. See the UV_EAI_* constants. 87 88 Call :c:func:`uv_freeaddrinfo` to free the addrinfo structure. 89 90 .. versionchanged:: 1.3.0 the callback parameter is now allowed to be NULL, 91 in which case the request will run **synchronously**. 92 93.. c:function:: void uv_freeaddrinfo(struct addrinfo* ai) 94 95 Free the struct addrinfo. Passing NULL is allowed and is a no-op. 96 97.. c:function:: int uv_getnameinfo(uv_loop_t* loop, uv_getnameinfo_t* req, uv_getnameinfo_cb getnameinfo_cb, const struct sockaddr* addr, int flags) 98 99 Asynchronous :man:`getnameinfo(3)`. 100 101 Returns 0 on success or an error code < 0 on failure. If successful, the 102 callback will get called sometime in the future with the lookup result. 103 Consult `man -s 3 getnameinfo` for more details. 104 105 .. versionchanged:: 1.3.0 the callback parameter is now allowed to be NULL, 106 in which case the request will run **synchronously**. 107 108.. seealso:: The :c:type:`uv_req_t` API functions also apply. 109