GETNAMEINFO(3)             POSIX Programmer's Manual            GETNAMEINFO(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       getnameinfo -- get name information

SSYYNNOOPPSSIISS
       #include <sys/socket.h>
       #include <netdb.h>

       int getnameinfo(const struct sockaddr *restrict _s_a, socklen_t _s_a_l_e_n,
           char *restrict _n_o_d_e, socklen_t _n_o_d_e_l_e_n, char *restrict _s_e_r_v_i_c_e,
           socklen_t _s_e_r_v_i_c_e_l_e_n, int _f_l_a_g_s);

DDEESSCCRRIIPPTTIIOONN
       The _g_e_t_n_a_m_e_i_n_f_o() function shall translate a socket address to a node
       name and service location, all of which are defined as in
       _f_r_e_e_a_d_d_r_i_n_f_o().

       The _s_a argument points to a socket address structure to be translated.
       The _s_a_l_e_n argument contains the length of the address pointed to by _s_a.

       If the socket address structure contains an IPv4-mapped IPv6 address or
       an IPv4-compatible IPv6 address, the implementation shall extract the
       embedded IPv4 address and lookup the node name for that IPv4 address.

       If the address is the IPv6 unspecified address (""::::""), a lookup shall
       not be performed and the behavior shall be the same as when the node's
       name cannot be located.

       If the _n_o_d_e argument is non-NULL and the _n_o_d_e_l_e_n argument is non-zero,
       then the _n_o_d_e argument points to a buffer able to contain up to _n_o_d_e_l_e_n
       bytes that receives the node name as a null-terminated string. If the
       _n_o_d_e argument is NULL or the _n_o_d_e_l_e_n argument is zero, the node name
       shall not be returned. If the node's name cannot be located, the
       numeric form of the address contained in the socket address structure
       pointed to by the _s_a argument is returned instead of its name.

       If the _s_e_r_v_i_c_e argument is non-NULL and the _s_e_r_v_i_c_e_l_e_n argument is non-
       zero, then the _s_e_r_v_i_c_e argument points to a buffer able to contain up
       to _s_e_r_v_i_c_e_l_e_n bytes that receives the service name as a null-terminated
       string.  If the _s_e_r_v_i_c_e argument is NULL or the _s_e_r_v_i_c_e_l_e_n argument is
       zero, the service name shall not be returned. If the service's name
       cannot be located, the numeric form of the service address (for
       example, its port number) shall be returned instead of its name.

       The _f_l_a_g_s argument is a flag that changes the default actions of the
       function. By default the fully-qualified domain name (FQDN) for the
       host shall be returned, but:

        *  If the flag bit NI_NOFQDN is set, only the node name portion of the
           FQDN shall be returned for local hosts.

        *  If the flag bit NI_NUMERICHOST is set, the numeric form of the
           address contained in the socket address structure pointed to by the
           _s_a argument shall be returned instead of its name.

        *  If the flag bit NI_NAMEREQD is set, an error shall be returned if
           the host's name cannot be located.

        *  If the flag bit NI_NUMERICSERV is set, the numeric form of the
           service address shall be returned (for example, its port number)
           instead of its name.

        *  If the flag bit NI_NUMERICSCOPE is set, the numeric form of the
           scope identifier shall be returned (for example, interface index)
           instead of its name. This flag shall be ignored if the _s_a argument
           is not an IPv6 address.

        *  If the flag bit NI_DGRAM is set, this indicates that the service is
           a datagram service (SOCK_DGRAM). The default behavior shall assume
           that the service is a stream service (SOCK_STREAM).

       NNootteess::

                  1. The two NI_NUMERICxxx flags are required to support the
                     --nn flag that many commands provide.

                  2. The NI_DGRAM flag is required for the few AF_INET and
                     AF_INET6 port numbers (for example, [512,514]) that
                     represent different services for UDP and TCP.

       The _g_e_t_n_a_m_e_i_n_f_o() function shall be thread-safe.

RREETTUURRNN VVAALLUUEE
       A zero return value for _g_e_t_n_a_m_e_i_n_f_o() indicates successful completion;
       a non-zero return value indicates failure. The possible values for the
       failures are listed in the ERRORS section.

       Upon successful completion, _g_e_t_n_a_m_e_i_n_f_o() shall return the _n_o_d_e and
       _s_e_r_v_i_c_e names, if requested, in the buffers provided. The returned
       names are always null-terminated strings.

EERRRROORRSS
       The _g_e_t_n_a_m_e_i_n_f_o() function shall fail and return the corresponding
       value if:

       [EAI_AGAIN] The name could not be resolved at this time. Future
                   attempts may succeed.

       [EAI_BADFLAGS]
                   The _f_l_a_g_s had an invalid value.

       [EAI_FAIL]  A non-recoverable error occurred.

       [EAI_FAMILY]
                   The address family was not recognized or the address length
                   was invalid for the specified family.

       [EAI_MEMORY]
                   There was a memory allocation failure.

       [EAI_NONAME]
                   The name does not resolve for the supplied parameters.

                   NI_NAMEREQD is set and the host's name cannot be located,
                   or both _n_o_d_e_n_a_m_e and _s_e_r_v_n_a_m_e were null.

       [EAI_OVERFLOW]
                   An argument buffer overflowed. The buffer pointed to by the
                   _n_o_d_e argument or the _s_e_r_v_i_c_e argument was too small.

       [EAI_SYSTEM]
                   A system error occurred. The error code can be found in
                   _e_r_r_n_o.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       If the returned values are to be used as part of any further name
       resolution (for example, passed to _g_e_t_a_d_d_r_i_n_f_o()), applications should
       provide buffers large enough to store any result possible on the
       system.

       Given the IPv4-mapped IPv6 address ""::::ffffffff::11..22..33..44"", the implementation
       performs a lookup as if the socket address structure contains the IPv4
       address ""11..22..33..44"".

       The IPv6 unspecified address (""::::"") and the IPv6 loopback address
       (""::::11"") are not IPv4-compatible addresses.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _e_n_d_s_e_r_v_e_n_t(), _f_r_e_e_a_d_d_r_i_n_f_o(), _g_a_i___s_t_r_e_r_r_o_r(), _i_n_e_t___n_t_o_p(), _s_o_c_k_e_t()

       The Base Definitions volume of POSIX.1-2017, <<nneettddbb..hh>>, <<ssyyss__ssoocckkeett..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                       GETNAMEINFO(3)
