KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
netdb.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  netdb.h
4  Copyright (C) 2014 Lawrence Sebald
5 
6 */
7 
8 /** \file netdb.h
9  \brief Network address database functionality.
10 
11  This file contains functions related to network address lookups, usually
12  performed through DNS.
13 
14  \author Lawrence Sebald
15 */
16 
17 #ifndef __NETDB_H
18 #define __NETDB_H
19 
20 #include <sys/cdefs.h>
21 
22 __BEGIN_DECLS
23 
24 #include <netinet/in.h>
25 #include <sys/socket.h>
26 #include <inttypes.h>
27 
28 /** \brief Network host entry.
29 
30  This structure describes a network host entry in the address database. When
31  looking up an address with the gethostbyname() function, one of these will
32  be returned with information about the host.
33 
34  \headerfile netdb.h
35 */
36 struct hostent {
37  char *h_name; /**< \brief Official name of the host. */
38  char **h_aliases; /**< \brief Alternative host names. */
39  int h_addrtype; /**< \brief Address type. */
40  int h_length; /**< \brief Length of address, in bytes. */
41  char **h_addr_list; /**< \brief Network addresses of host. */
42 #define h_addr h_addr_list[0] /**< \brief Primary network address. */
43 };
44 
45 /** \brief Network address information structure.
46 
47  This structure describes information on an address in the database. This
48  structure is used by functions such as getaddrinfo() to return information
49  about the specified host.
50 
51  \headerfile netdb.h
52 */
53 struct addrinfo {
54  int ai_flags; /**< \brief Input flags.
55  \see addrinfo_flags */
56  int ai_family; /**< \brief Socket address family. */
57  int ai_socktype; /**< \brief Socket type. */
58  int ai_protocol; /**< \brief Socket protocol. */
59  socklen_t ai_addrlen; /**< \brief Address length. */
60  struct sockaddr *ai_addr; /**< \brief Address structure. */
61  char *ai_canonname; /**< \brief Canonical name. */
62  struct addrinfo *ai_next; /**< \brief Next address entry (if any). */
63 };
64 
65 /** \brief Error value for gethostbyname().
66  \see herrno_vals */
67 extern int h_errno;
68 
69 /** \defgroup herrno_vals Error values for the h_errno variable
70 
71  These are the possible values for h_errno, indicating errors returns from
72  the gethostbyname() function.
73 
74  @{
75 */
76 #define HOST_NOT_FOUND 1 /**< \brief Hostname not found. */
77 #define TRY_AGAIN 2 /**< \brief Try the request again. */
78 #define NO_RECOVERY 3 /**< \brief A non-recoverable error. */
79 #define NO_DATA 4 /**< \brief Host found, but no data. */
80 /** @} */
81 
82 /** \defgroup addrinfo_errors Errors for the getaddrinfo() function
83 
84  These are the possible error return values from the getaddrinfo() function.
85 
86  @{
87 */
88 #define EAI_AGAIN 1 /**< \brief Try the request again. */
89 #define EAI_BADFLAGS 2 /**< \brief Invalid hint flags. */
90 #define EAI_FAIL 3 /**< \brief A non-recoverable error. */
91 #define EAI_FAMILY 4 /**< \brief Invalid address family. */
92 #define EAI_MEMORY 5 /**< \brief Memory allocation error. */
93 #define EAI_NONAME 6 /**< \brief Hostname not found. */
94 #define EAI_SERVICE 7 /**< \brief Invalid service value. */
95 #define EAI_SOCKTYPE 8 /**< \brief Invalid socket type. */
96 #define EAI_SYSTEM 9 /**< \brief System error, check errno. */
97 #define EAI_OVERFLOW 10 /**< \brief Argument buffer overflow. */
98 /** @} */
99 
100 /** \defgroup addrinfo_flags Flags for ai_flags in struct addrinfo
101 
102  These are the flags that can be set in the ai_flags field of struct
103  addrinfo. These values can be bitwise ORed together.
104 
105  Currently only AI_PASSIVE is actually supported by the getaddrinfo()
106  function.
107 
108  @{
109 */
110 #define AI_PASSIVE 0x00000001 /**< \brief Address intended for bind(). */
111 #define AI_CANONNAME 0x00000002 /**< \brief Request canonical name. */
112 #define AI_NUMERICHOST 0x00000004 /**< \brief Inhibit host resolution. */
113 #define AI_NUMERICSERV 0x00000008 /**< \brief Inhibit service resolution. */
114 #define AI_V4MAPPED 0x00000010 /**< \brief Return v4-mapped IPv6 addrs. */
115 #define AI_ALL 0x00000020 /**< \brief Query for both IPv4 and IPv6. */
116 #define AI_ADDRCONFIG 0x00000040 /**< \brief Only query for IPv4/IPv6 addrs
117  the system has a valid addr. */
118 /** @} */
119 
120 /** \brief Free an address information structure returned by getaddrinfo().
121 
122  This function cleans up any memory associated with the specified
123  struct addrinfo, which was returned previously by a call to getaddrinfo().
124 
125  \param ai The struct addrinfo to clean up.
126 */
127 void freeaddrinfo(struct addrinfo *ai);
128 
129 /** \brief Get information about a specified addresss.
130 
131  This function translates the name of a host and service into a set of socket
132  addresses and related information to be used in creating a socket. This
133  includes potentially looking up the host information in the network address
134  database (and thus in DNS possibly as well).
135 
136  \param nodename The host to look up.
137  \param servname The service to look up.
138  \param hints Hints used in aiding lookup.
139  \param res The resulting address information.
140  \return 0 on success, non-zero error code on failure.
141  \see addrinfo_errors
142 */
143 int getaddrinfo(const char *nodename, const char *servname,
144  const struct addrinfo *hints, struct addrinfo **res);
145 
146 /** \brief Look up a host by its name.
147 
148  This function queries the network address database (possibly recursively)
149  for the network address of the specified hostname. This will first search
150  any local databases before querying remote databases (such as a DNS server)
151  for the host specified.
152 
153  \param name The hostname to look up.
154  \return A pointer to a host entry on success or NULL on
155  failure. h_errno is set on failure to indicate the
156  error that occurred.
157 
158  \note This function is non-reentrant. getaddrinfo() should
159  (in general) be used instead of this function.
160 */
161 struct hostent *gethostbyname(const char *name);
162 
163 /** \brief Look up a host by its name and address family.
164 
165  This function queries the network address database (possibly recursively)
166  for the network address of the specified hostname. This will first search
167  any local databases before querying remote databases (such as a DNS server)
168  for the host specified.
169 
170  This function allows you to specify the address family that you wish the
171  returned hostent to contain. This function is a GNU extension and has not
172  been specified by any POSIX specification.
173 
174  \param name The hostname to look up.
175  \param af The address family to use for lookups (AF_INET or
176  AF_INET6).
177  \return A pointer to a host entry on success or NULL on
178  failure. h_errno is set on failure to indicate the
179  error that occurred.
180 
181  \note This function is non-reentrant. getaddrinfo() should
182  (in general) be used instead of this function.
183 */
184 struct hostent *gethostbyname2(const char *name, int af);
185 
186 __END_DECLS
187 
188 #endif /* !__NETDB_H */
socklen_t ai_addrlen
Address length.
Definition: netdb.h:59
void freeaddrinfo(struct addrinfo *ai)
Free an address information structure returned by getaddrinfo().
char ** h_addr_list
Network addresses of host.
Definition: netdb.h:41
Network host entry.
Definition: netdb.h:36
int getaddrinfo(const char *nodename, const char *servname, const struct addrinfo *hints, struct addrinfo **res)
Get information about a specified addresss.
Definitions for the Internet address family.
struct hostent * gethostbyname2(const char *name, int af)
Look up a host by its name and address family.
char * ai_canonname
Canonical name.
Definition: netdb.h:61
Socket address structure.
Definition: socket.h:38
char ** h_aliases
Alternative host names.
Definition: netdb.h:38
__uint32_t socklen_t
Socket length type.
Definition: socket.h:30
int ai_protocol
Socket protocol.
Definition: netdb.h:58
char * h_name
Official name of the host.
Definition: netdb.h:37
int h_length
Length of address, in bytes.
Definition: netdb.h:40
int ai_socktype
Socket type.
Definition: netdb.h:57
int h_addrtype
Address type.
Definition: netdb.h:39
struct addrinfo * ai_next
Next address entry (if any).
Definition: netdb.h:62
Main sockets header.
struct hostent * gethostbyname(const char *name)
Look up a host by its name.
Network address information structure.
Definition: netdb.h:53
int ai_flags
Input flags.
Definition: netdb.h:54
struct sockaddr * ai_addr
Address structure.
Definition: netdb.h:60
int h_errno
Error value for gethostbyname().
int ai_family
Socket address family.
Definition: netdb.h:56