From 8d1da2e74a2ad861ec64a6439e30200a09d5db48 Mon Sep 17 00:00:00 2001 From: millert <> Date: Mon, 20 Dec 2004 21:13:00 +0000 Subject: New getaddrinfo.3 man page, derived from the ISC version and fleshed out a bit by me. Needs more work. --- src/lib/libc/net/getaddrinfo.3 | 300 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 300 insertions(+) create mode 100644 src/lib/libc/net/getaddrinfo.3 (limited to 'src/lib') diff --git a/src/lib/libc/net/getaddrinfo.3 b/src/lib/libc/net/getaddrinfo.3 new file mode 100644 index 0000000000..2209100c8b --- /dev/null +++ b/src/lib/libc/net/getaddrinfo.3 @@ -0,0 +1,300 @@ +.\" $OpenBSD: getaddrinfo.3,v 1.31 2004/12/20 21:13:00 millert Exp $ +.\" +.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2000, 2001 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH +.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM +.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE +.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 20, 2004 +.Dt GETADDRINFO 3 +.Os +.Sh NAME +.Nm getaddrinfo , +.Nm freeaddrinfo +.Nd socket address structure to host and service name +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Ft int +.Fn getaddrinfo "const char *hostname" "const char *servname" "const struct addrinfo *hints" "struct addrinfo **res" +.Ft void +.Fn freeaddrinfo "struct addrinfo *ai" +.Sh DESCRIPTION +.Fn getaddrinfo +is used to get a list of +.Dv IP +addresses and port numbers for host +.Fa hostname +and service +.Fa servname . +It is a replacement for and provides more flexibility than the +.Xr gethostbyname 3 +and +.Xr getservbyname 3 +functions. +.Pp +.Fa hostname +and +.Fa servname +are either pointers to NUL-terminated strings or the null pointer. +An acceptable value for +.Fa hostname +is either a host name or a numeric host address string consisting +of a dotted decimal IPv4 address or an IPv6 address. +The +.Fa servname +is either a decimal port number or a service name listed in +.Xr services 5 . +At least one of +.Fa hostname +and +.Fa servname +must be non-null. +.Pp +.Fa hints +is an optional pointer to a +.Li struct addrinfo , +as defined by +.Aq Pa netdb.h : +.Bd -literal +struct addrinfo { + int ai_flags; /* input flags */ + int ai_family; /* protocol family for socket */ + int ai_socktype; /* socket type */ + int ai_protocol; /* protocol for socket */ + socklen_t ai_addrlen; /* length of socket-address */ + struct sockaddr *ai_addr; /* socket-address for socket */ + char *ai_canonname; /* canonical name for service location */ + struct addrinfo *ai_next; /* pointer to next in list */ +}; +.Ed +.Pp +This structure can be used to provide hints concerning the type of socket +that the caller supports or wishes to use. +The caller can supply the following structure elements in +.Fa hints : +.Bl -tag -width "ai_socktypeXX" +.It Fa ai_family +The protocol family that should be used. +When +.Fa ai_family +is set to +.Dv PF_UNSPEC , +it means the caller will accept any protocol family supported by the +operating system. +.It Fa ai_socktype +Denotes the type of socket that is wanted: +.Dv SOCK_STREAM , +.Dv SOCK_DGRAM +or +.Dv SOCK_RAW . +When +.Fa ai_socktype +is zero the caller will accept any socket type. +.It Fa ai_protocol +Indicates which transport protocol is desired, +.Dv IPPROTO_UDP +or +.Dv IPPROTO_TCP . +If +.Fa ai_protocol +is zero the caller will accept any protocol. +.It Fa ai_flags +Flag bits. +.Bl -tag -width "AI_CANONNAMEXX" +.It Dv AI_CANONNAME +If the +.Dv AI_CANONNAME +bit is set, a successful call to +.Fn getaddrinfo +will return a NUL-terminated string containing the canonical name +of the specified hostname in the +.Fa ai_canonname +element of the first +.Li addrinfo +structure returned. +.It Dv AI_NUMERICHOST +If the +.Dv AI_NUMERICHOST +bit is set, it indicates that +.Fa hostname +should be treated as a numeric string defining an IPv4 or IPv6 address +and no name resolution should be attempted. +.It Dv AI_PASSIVE +If the +.Dv AI_PASSIVE +bit is set it indicates that the returned socket address structure +is intended for used in a call to +.Xr bind 2 . +In this case, if the +.Fa hostname +argument is a the null pointer, then the IP address portion of the +socket address structure will be set to +.Dv INADDR_ANY +for an IPv4 address or +.Dv IN6ADDR_ANY_INIT +for an IPv6 address. +.Pp +If the +.Dv AI_PASSIVE +bit is not set, the returned socket address structure will be ready +for use in a call to +.Xr connect 2 +for a connection-oriented protocol or +.Xr connect 2 , +.Xr sendto 2 +or +.Xr sendmsg 2 +if a connectionless protocol was chosen. +The +.Dv IP +address portion of the socket address structure will be set to the +loopback address if +.Fa hostname +is the null pointer and the +.Dv AI_PASSIVE +is not set. +.El +.El +.Pp +All other elements of the +.Li addrinfo +structure passed via +.Fa hints +must be zero or the null pointer. +.Pp +If +.Fa hints +is the null pointer, +.Fn getaddrinfo +behaves as if the caller provided a +.Li struct addrinfo +initialized to zero and with +.Fa ai_family +set to +.Dv PF_UNSPEC . +.Pp +After a successful call to +.Fn getaddrinfo , +.Fa *res +is a pointer to a linked list of one or more +.Li addrinfo +structures. +The list can be traversed by following the +.Fa ai_next +pointer in each +.Li addrinfo +structure until a null pointer is encountered. +The three members, +.Fa ai_family, +.Fa ai_socktype, +and +.Fa ai_protocol +in each returned +.Li addrinfo +structure are suitable for a call to +.Xr socket 2 . +For each +.Li addrinfo +structure in the list, the +.Fa ai_addr +member points to a filled-in socket address structure of length +.Fa ai_addrlen . +.Pp +All of the information returned by +.Fn getaddrinfo +is dynamically allocated: the +.Li addrinfo +structures themselves as well as the socket address structures and +the canonical host name strings included in the +.Li addrinfo +structures. +.Pp +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn getaddrinfo +is released by the +.Fn freeaddrinfo +function. +The +.Fa ai +pointer should be a +.Li addrinfo +structure created by a call to +.Fn getaddrinfo . +.Sh RETURN VALUES +.Fn getaddrinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. +If both +.Fa hostname +and +.Fa servname +are +.Dv NULL , +.Fn getaddrinfo +returns +.Dv EAI_NONAME . +.Sh SEE ALSO +.Xr bind 2 , +.Xr connect 2 , +.Xr send 2 , +.Xr socket 2 , +.Xr gai_strerror 3 , +.Xr gethostbyname 3 , +.Xr getnameinfo 3 , +.Xr getservbyname 3 , +.Xr resolver 3 , +.Xr hosts 5 , +.Xr resolv.conf 5 , +.Xr services 5 , +.Xr hostname 7 , +.Xr named 8 +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%T Basic Socket Interface Extensions for IPv6 +.%R RFC 3493 +.%D February 2003 +.Re +.Rs +.%A Tatsuya Jinmei +.%A Atsushi Onoe +.%T "An Extension of Format for IPv6 Scoped Addresses" +.%R internet draft +.%N draft-ietf-ipngwg-scopedaddr-format-02.txt +.%O work in progress material +.Re +.Rs +.%A Craig Metz +.%T Protocol Independence Using the Sockets API +.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" +.%D June 2000 +.Re +.Sh STANDARDS +The +.Fn getaddrinfo +function is defined by the +.St -p1003.1g-2000 +draft specification and documented in +.Dv "RFC 3493" , +.Dq Basic Socket Interface Extensions for IPv6 . +.Sh BUGS +Due to the use of dynamic allocation, +.Fn getaddrinfo +is not thread-safe. -- cgit v1.2.3-55-g6feb