The <netdb.h>
header defines functions useful for network database operations.
Structures and Types
addrinfo Struct
Purpose
This structure contains the information obtained from the address.
Declared In
posix/netdb.h
Prototype
struct addrinfo { int ai_flags; int ai_family; int ai_socktype; int ai_protocol; size_t ai_addrlen; char *ai_canonname; struct sockaddr *ai_addr; struct addrinfo *ai_next; }
Fields
-
ai_flags
-
AI_PASSIVE
,AI_CANONNAME
,AI_NUMERICHOST
. -
ai_family
-
PF_xxx
. -
ai_socktype
-
SOCK_xxx
. -
ai_protocol
- 0 or
IPPROTO_xxx
for IPv4 and IPv6. -
ai_addrlen
- The length of
ai_addr
. -
ai_canonname
- Canonical name for hostname.
-
ai_addr
- Binary address.
-
ai_next
- Next structure in linked list.
Comments
All addresses are supplied in host order and returned in network order (suitable for use in system calls).
hostent Struct
Purpose
This structure contains either the information obtained from the name server or database entries supplied by the system.
Declared In
posix/netdb.h
Prototype
struct hostent { char *h_name; char **h_aliases; int h_addrtype; int h_length; char **h_addr_list; }
Fields
-
h_name
- Official name of the host.
-
h_aliases
- A list of alternative names for the host.
-
h_addrtype
- Host address type.
-
h_length
- The length, in bytes, of the address.
-
h_addr_list
- List of addresses from name server.
Comments
All addresses are supplied in host order and returned in network order (suitable for use in system calls).
netent Struct
Purpose
This structure contains the information obtained from the network.
Declared In
posix/netdb.h
Prototype
struct netent { char *n_name; char **n_aliases; int n_addrtype; unsigned long n_net; }
Fields
-
n_name
- Official name of the network.
-
n_aliases
- A list of alternative names for the network.
-
n_addrtype
- Network address type.
-
n_net
- The network number.
Comments
All addresses are supplied in host order and returned in network order (suitable for use in system calls).
protoent Struct
Purpose
This structure contains the information obtained from the protocol.
Declared In
posix/netdb.h
Prototype
struct protoent { char *p_name; char **p_aliases; int p_proto; }
Fields
-
p_name
- Official name of the protocol.
-
p_aliases
- A list of alternative names for the protocol.
-
p_proto
- The protocol number.
Comments
All addresses are supplied in host order and returned in network order (suitable for use in system calls).
servent Struct
Purpose
This structure contains the information obtained from the service.
Declared In
posix/netdb.h
Prototype
struct servent { char *s_name; char **s_aliases; int s_port; char *s_proto; }
Fields
-
s_name
- Official name of the service.
-
s_aliases
- A list of alternative names for the service.
-
s_port
- The port number.
-
s_proto
- The protocol to use.
Comments
All addresses are supplied in host order and returned in network order (suitable for use in system calls).
Functions and Macros
endhostent Function
Purpose
Declared In
posix/netdb.h
Prototype
void endhostent ( void )
Compatibility
This function is not in the C99 specification.
endnetent Function
Purpose
Closes the connection to the database, releasing any open file descriptor.
Declared In
posix/netdb.h
Prototype
void endnetent ( void )
Compatibility
This function is not in the C99 specification.
endprotoent Function
Purpose
Closes the connection to the database, releasing any open file descriptor.
Declared In
posix/netdb.h
Prototype
void endprotoent ( void )
Compatibility
This function is not in the C99 specification.
endservent Function
Purpose
Closes the connection to the database, releasing any open file descriptor.
Declared In
posix/netdb.h
Prototype
void endservent ( void )
Compatibility
This function is not in the C99 specification.
freeaddrinfo Function
Purpose
Returns the socket address structures and canonical node name strings pointed to by the addrinfo
structures.
Declared In
posix/netdb.h
Prototype
void freeaddrinfo (
struct addrinfo *ai
)
Parameters
-
→ ai
- The
addrinfo
structure pointed to by theai
argument is freed, along with any dynamic storage pointed to by the structure. This operation is repeated until aNULL
ai_next
pointer is encountered.
Compatibility
This function is not in the C99 specification.
freehostent Function
Purpose
Releases the dynamically allocated memory of the hostent
structure.
Returns
Returns a pointer to an object of the hostent
structure.
Declared In
posix/netdb.h
Prototype
void freehostent (
struct hostent *ip
)
Parameters
Compatibility
This function is not in the C99 specification.
This function is a Palm OS extension (not present in C99 or Unix).
gai_strerror Function
Purpose
Aids applications in printing error messages based on the EAI_xxx
codes.
Declared In
posix/netdb.h
Prototype
const char *gai_strerror (
int ecode
)
Parameters
Returns
Returns a pointer to a string whose contents indicate an unknown error.
Compatibility
This function is not in the C99 specification.
getaddrinfo Function
Purpose
Protocol-independent nodename-to-address translation.
Declared In
posix/netdb.h
Prototype
int getaddrinfo ( const char *nodename
, const char *servname
, const struct addrinfo *hints
, struct addrinfo **res
)
Parameters
-
→ nodename
- A pointer to null-terminated strings or
NULL
. -
→ servname
- A pointer to null-terminated strings or
NULL
. -
→ hints
- Hints concerning the type of socket that the caller supports.
-
← res
- A pointer to a linked list of one or more
addrinfo
structures.
Returns
Returns a set of socket addresses and associated information to be used in creating a socket with which to address the specified service.
Comments
One or both of the nodename
and servname
parameters must be a non-NULL
pointer.
If nodename
is not NULL
, the requested service location is named by nodename
; otherwise, the requested service location is local to the caller. If servname
is NULL
, the call returns network-level addresses for the specified nodename
. If servname
is not NULL
, it is a null-terminated character string identifying the requested service.
Compatibility
This function is not in the C99 specification.
See Also
gethostbyname()
, getservbyname()
gethostbyaddr Function
Purpose
Searches for the specified host in the current domain and its parents unless the name ends in a dot.
Declared In
posix/netdb.h
Prototype
struct hostent *gethostbyaddr ( const char *addr
, intlen
, inttype
)
Parameters
-
→ addr
- Host address type.
-
→ len
- The length, in bytes, of the address.
-
→ type
- A named constant that indicates the naming scheme under which the lookup is performed. Must be specified as
AF_INET
.
Returns
Returns a pointer to an object of the hostent
structure, describing an Internet host referenced by address.
Compatibility
This function is not in the C99 specification.
gethostbyname Function
Purpose
Searches for the specified host in the current domain and its parents unless the name ends in a dot.
Declared In
posix/netdb.h
Prototype
struct hostent *gethostbyname (
const char *name
)
Parameters
Returns
Returns a pointer to an object of the hostent
structure, describing an Internet host referenced by name.
Compatibility
This function is not in the C99 specification.
gethostbyname2 Function
Purpose
An evolution of gethostbyname()
that allows lookups in address families other than AF_INET
.
Declared In
posix/netdb.h
Prototype
struct hostent *gethostbyname2 ( const char *name
, intaf
)
Parameters
Returns
Returns a pointer to an object of the hostent
structure, describing an Internet host referenced by name.
Compatibility
This function is not in the C99 specification.
This function is a Palm OS extension (not present in C99 or Unix).
gethostent Function
Purpose
Reads the next entry in the database, opening and closing a connection to the database as necessary.
Declared In
posix/netdb.h
Prototype
struct hostent *gethostent ( void )
Returns
Returns a pointer to an object of the hostent
structure.
Compatibility
This function is not in the C99 specification.
getipnodebyaddr Function
Purpose
Returns the address of a network host.
Declared In
posix/netdb.h
Prototype
struct hostent *getipnodebyaddr ( const void *src
, size_tlen
, intaf
, int *error_num
)
Parameters
-
→ src
- The name of the host whose network address to look up.
-
→ len
- The length, in bytes, of the address.
-
→ af
- Must be specified as
AF_INET
orAF_INET6
. -
← error_num
- A
NULL
pointer is returned if an error occurred, anderror_num
contains an error code from the following list:HOST_NOT_FOUND
,NO_ADDRESS
,NO_RECOVERY
, orTRY_AGAIN
.
Returns
Returns a pointer to an object of the hostent
structure, describing an Internet host referenced by address.
Compatibility
This function is not in the C99 specification.
This function is a Palm OS extension (not present in C99 or Unix).
getipnodebyname Function
Purpose
Returns the name of a network host.
Declared In
posix/netdb.h
Prototype
struct hostent *getipnodebyname ( const char *name
, intaf
, intflags
, int *error_num
)
Parameters
-
→ name
- Official name of the host.
-
→ af
- Must be specified as
AF_INET
orAF_INET6
. -
→ flags
- Specifies additional options:
AI_V4MAPPED
,AI_ALL
, orAI_ADDRCONFIG
. More than one option can be specified by logically ORing them together.flags
should be set to zero (0) if no options are desired. -
← error_num
- A
NULL
pointer is returned if an error occurred, anderror_num
contains an error code from the following list:HOST_NOT_FOUND
,NO_ADDRESS
,NO_RECOVERY
, orTRY_AGAIN
.
Returns
Returns a pointer to an object of the hostent
structure, describing an Internet host referenced by name.
Compatibility
This function is not in the C99 specification.
This function is a Palm OS extension (not present in C99 or Unix).
getnameinfo Function
Purpose
Translates address-to-nodename in a protocol-independent manner.
Declared In
posix/netdb.h
Prototype
int getnameinfo ( const struct sockaddr *sa
, size_tsalen
, char *host
, size_thostlen
, char *serv
, size_tservlen
, intflags
)
Parameters
-
→ sa
- A
sockaddr
structure. -
→ salen
- The length, in bytes, of the
sockaddr
structure. -
→ host
- The buffer that holds the IP address.
-
→ hostlen
- The length, in bytes, of the IP address buffer.
-
→ serv
- The buffer that holds the port number.
-
→ servlen
- The length, in bytes, of the port number buffer.
-
→ flags
- Changes the default actions of this function.
Returns
Returns text strings for the IP address and port number in user-provided buffers.
Compatibility
This function is not in the C99 specification.
getnetbyaddr Function
Purpose
Searches from the beginning of the file until a matching network address is found, or until EOF is encountered.
Declared In
posix/netdb.h
Prototype
struct netent *getnetbyaddr ( unsigned longnet
, inttype
)
Parameters
Returns
Returns a pointer to an object of the netent
structure, describing the network database.
Compatibility
This function is not in the C99 specification.
getnetbyname Function
Purpose
Searches from the beginning of the file until a matching network name is found, or until EOF is encountered.
Declared In
posix/netdb.h
Prototype
struct netent *getnetbyname (
const char *name
)
Parameters
Returns
Returns a pointer to an object of the netent
structure, describing the network database.
Compatibility
This function is not in the C99 specification.
getnetent Function
Purpose
Reads the next line of the file, opening the file if necessary.
Declared In
posix/netdb.h
Prototype
struct netent *getnetent ( void )
Returns
Returns a pointer to an object of the netent
structure, describing the network database.
Compatibility
This function is not in the C99 specification.
getprotobyname Function
Purpose
Sequentially searches from the beginning of the file until a matching protocol name is found, or until EOF is encountered.
Declared In
posix/netdb.h
Prototype
struct protoent *getprotobyname (
const char *name
)
Parameters
Returns
Returns a pointer to an object of the protoent
structure, describing the network database.
Compatibility
This function is not in the C99 specification.
getprotobynumber Function
Purpose
Sequentially searches from the beginning of the file until a matching protocol number is found, or until EOF is encountered.
Declared In
posix/netdb.h
Prototype
struct protoent *getprotobynumber (
int proto
)
Parameters
Returns
Returns a pointer to an object of the protoent
structure, describing the network database.
Compatibility
This function is not in the C99 specification.
getprotoent Function
Purpose
Reads the next line of the file, opening the file if necessary.
Declared In
posix/netdb.h
Prototype
struct protoent *getprotoent ( void )
Returns
Returns a pointer to an object of the protoent
structure, describing the network database.
Compatibility
This function is not in the C99 specification.
getservbyname Function
Purpose
Searches from the beginning of the file until a matching protocol name is found, or until EOF is encountered.
Declared In
posix/netdb.h
Prototype
struct servent *getservbyname ( const char *name
, const char *proto
)
Parameters
Returns
Returns a pointer to an object of the servent
structure, describing the network services database.
Compatibility
This function is not in the C99 specification.
getservbyport Function
Purpose
Searches from the beginning of the file until a matching port number is found, or until EOF is encountered.
Declared In
posix/netdb.h
Prototype
struct servent *getservbyport ( intport
, const char *proto
)
Parameters
Returns
Returns a pointer to an object of the servent
structure, describing the network services database.
Compatibility
This function is not in the C99 specification.
getservent Function
Purpose
Reads the next line of the file, opening the file if necessary.
Declared In
posix/netdb.h
Prototype
struct servent *getservent ( void )
Returns
Returns a pointer to an object of the servent
structure, describing the network services database.
Compatibility
This function is not in the C99 specification.
hstrerror Function
Purpose
Returns a string that is the message text corresponding to the value of the err
parameter.
Declared In
posix/netdb.h
Prototype
const char *hstrerror (
int err
)
Parameters
Returns
Returns a string that is the message text corresponding to the value of the err
parameter.
Compatibility
This function is not in the C99 specification.
This function is a Palm OS extension (not present in C99 or Unix).
sethostent Function
Purpose
Requests the use of a connected TCP socket for queries.
Declared In
posix/netdb.h
Prototype
void sethostent (
int stayopen
)
Parameters
-
→ stayopen
- If the
stayopen
flag is non-zero, sets the option to send all queries to the name server using TCP and to retain the connection after each call togethostbyname()
,gethostbyname2()
, orgethostbyaddr()
. Otherwise, queries are performed using UDP datagrams.
Compatibility
This function is not in the C99 specification.
See Also
gethostbyaddr()
, gethostbyname()
, gethostbyname2()
setnetent Function
Purpose
Declared In
posix/netdb.h
Prototype
void setnetent (
int stayopen
)
Parameters
-
→ stayopen
- If non-zero, the network database is not closed after each call to
getnetbyname()
orgetnetbyaddr()
.
Compatibility
This function is not in the C99 specification.
See Also
getnetbyaddr()
, getnetbyname()
setprotoent Function
Purpose
Declared In
posix/netdb.h
Prototype
void setprotoent (
int stayopen
)
Parameters
-
→ stayopen
- If non-zero, the network database is not closed after each call to
getprotobyname()
orgetprotobynumber()
.
Compatibility
This function is not in the C99 specification.
See Also
getprotobyname()
, getprotobynumber()
setservent Function
Purpose
Declared In
posix/netdb.h
Prototype
void setservent (
int stayopen
)
Parameters
-
→ stayopen
- If non-zero, the network database is not closed after each call to
getservbyname()
orgetservbyport()
.
Compatibility
This function is not in the C99 specification.
See Also
getservbyname()
, getservbyport()