Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

15    netdb.h

Palm OS® Protein C/C++ Compiler Language & Library Reference

Palm OS® Developer Suite

     

The <netdb.h> header defines functions useful for network database operations.

Structures and Types ^TOP^

addrinfo Struct ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

endhostent Function ^TOP^

Purpose

Closes the TCP connection.

Declared In

posix/netdb.h

Prototype

void endhostent (
   void
)

Compatibility

This function is not in the C99 specification.

endnetent Function ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 the ai argument is freed, along with any dynamic storage pointed to by the structure. This operation is repeated until a NULL ai_next pointer is encountered.

Compatibility

This function is not in the C99 specification.

freehostent Function ^TOP^

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

ip
A pointer to an object of the hostent structure.

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 ^TOP^

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

ecode
An EAI_xxx code, such as EAI_ADDRFAMILY.

Returns

Returns a pointer to a string whose contents indicate an unknown error.

Compatibility

This function is not in the C99 specification.

getaddrinfo Function ^TOP^

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 ^TOP^

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,
   int len,
   int type
)

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 ^TOP^

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

name
Official name of the host.

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 ^TOP^

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,
   int af
)

Parameters

name
Official name of the host.
af
Must be specified as AF_INET or AF_INET6.

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 ^TOP^

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 ^TOP^

Purpose

Returns the address of a network host.

Declared In

posix/netdb.h

Prototype

struct hostent *getipnodebyaddr (
   const void *src,
   size_t len,
   int af,
   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 or AF_INET6.
error_num
A NULL pointer is returned if an error occurred, and error_num contains an error code from the following list: HOST_NOT_FOUND, NO_ADDRESS, NO_RECOVERY, or TRY_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 ^TOP^

Purpose

Returns the name of a network host.

Declared In

posix/netdb.h

Prototype

struct hostent *getipnodebyname (
   const char *name,
   int af,
   int flags,
   int *error_num
)

Parameters

name
Official name of the host.
af
Must be specified as AF_INET or AF_INET6.
flags
Specifies additional options: AI_V4MAPPED, AI_ALL, or AI_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, and error_num contains an error code from the following list: HOST_NOT_FOUND, NO_ADDRESS, NO_RECOVERY, or TRY_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 ^TOP^

Purpose

Translates address-to-nodename in a protocol-independent manner.

Declared In

posix/netdb.h

Prototype

int getnameinfo (
   const struct sockaddr *sa,
   size_t salen,
   char *host,
   size_t hostlen,
   char *serv,
   size_t servlen,
   int flags
)

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 ^TOP^

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 long net,
   int type
)

Parameters

net
The network number.
type
Network address type.

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 ^TOP^

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

name
Official name of the network.

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 ^TOP^

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 ^TOP^

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

name
Official name of the protocol.

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 ^TOP^

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

proto
Official name of the protocol.

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 ^TOP^

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 ^TOP^

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

name
Official name of the network.
proto
The protocol.

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 ^TOP^

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 (
   int port,
   const char *proto
)

Parameters

port
The port number.
proto
The protocol to use

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 ^TOP^

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 ^TOP^

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

err
The error.

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 ^TOP^

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 to gethostbyname(), gethostbyname2(), or gethostbyaddr(). Otherwise, queries are performed using UDP datagrams.

Compatibility

This function is not in the C99 specification.

See Also

gethostbyaddr(), gethostbyname(), gethostbyname2()

setnetent Function ^TOP^

Purpose

Opens and rewinds a file.

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() or getnetbyaddr().

Compatibility

This function is not in the C99 specification.

See Also

getnetbyaddr(), getnetbyname()

setprotoent Function ^TOP^

Purpose

Opens and rewinds a file.

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() or getprotobynumber().

Compatibility

This function is not in the C99 specification.

See Also

getprotobyname(), getprotobynumber()

setservent Function ^TOP^

Purpose

Opens and rewinds a file.

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() or getservbyport().

Compatibility

This function is not in the C99 specification.

See Also

getservbyname(), getservbyport()