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

15    Sockets & Network Support Reference

Low-Level Communications

Exploring Palm OS®

Overview ^TOP^

The structures, types, and functions described in this chapter are provided in several header files, including:

sys/socket.h
Defines functions and types for sending and receiving data using sockets, as well as for listening for and opening connections to remote devices.
posix/arpa/inet.h
Defines functions used for manipulating Internet addresses.
posix/netinet/in.h
Defines structures and functions used for converting between host and network addresses.
posix/netdb.h
Defines structures and functions used for performing network database operations, particularly Domain Name Resolution operations.
posix/sys/select.h
Provides the select() function, which provides a means of detecting the readiness state of file desriptors.

Each structure, type, or function indicates the header file in which it is defined.

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).

sockaddr Struct ^TOP^

Purpose

Defines a structure used by the kernel to store most addresses.

Declared In

posix/sys/socket.h

Prototype

struct sockaddr {
   sa_family_t sa_family;
   char sa_data[14];
}

Fields

sa_family
The address family.
sa_data
The address value.

sockaddr_in Struct ^TOP^

Purpose

Defines a structure used to store Internet addresses.

Declared In

posix/netinet/in.h

Prototype

struct sockaddr_in {
   sa_family_t sin_family;
   in_port_t sin_port;
   struct in_addr sin_addr;
   uint8_t sin_zero[8];
}

Fields

sin_family
AF_INET.
sin_port
The port number.
sin_addr
The IP address.
sin_zero
The address value; must be initialized to zero.

socklen_t Typedef ^TOP^

Purpose

A data type used to represent the size in bytes of socket related data.

Declared In

posix/sys/socket.h

Prototype

typedef unsigned int socklen_t


Functions and Macros ^TOP^

accept Function ^TOP^

Purpose

Accepts a connection on a socket by extracting the first connection request on the queue of pending connections, creating a new socket with the same properties of sock and allocating a new file descriptor for the socket.

Declared In

posix/sys/socket.h

Prototype

int accept (
   int sock,
   struct sockaddr *addr,
   socklen_t *addrlen
)

Parameters

sock
A socket that has been created with socket(), bound to an address with bind(), and listening for connections after a listen().
addr
A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
addrlen
Initially contains the amount of space pointed to by addr; on return, it contains the actual length (in bytes) of the address returned.

Returns

Returns a non-negative integer that is a descriptor for the accepted socket. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

Comments

This function is used to accept a connection when a remote system attempts to connect to a socket on which you have previously called listen().

See Also

bind(), connect(), listen(), select(), socket()

bind Function ^TOP^

Purpose

Assigns a name to an unnamed socket.

Declared In

posix/sys/socket.h

Prototype

int bind (
   int sock,
   const struct sockaddr *addr,
   socklen_t addrlen
)

Parameters

sock
A socket that has been created with socket() that exists in a namespace but has no name defined.
addr
A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
addrlen
Initially contains the amount of space pointed to by addr; on return, it contains the actual length (in bytes) of the address returned.

Returns

Returns zero (0) if the bind is successful. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

connect(), getsockname(), listen(), socket()

connect Function ^TOP^

Purpose

Initiates a connection on a socket.

Declared In

posix/sys/socket.h

Prototype

int connect (
   int sock,
   const struct sockaddr *addr,
   socklen_t addrlen
)

Parameters

sock
A socket.
addr
A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
addrlen
Initially contains the amount of space pointed to by addr; on return, it contains the actual length (in bytes) of the address returned.

Returns

Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

accept(), getsockname(), getsockopt(), select(), socket()

endhostent Function ^TOP^

Purpose

Closes the TCP connection.

Declared In

posix/netdb.h

Prototype

void endhostent (
   void
)

Parameters

None.

Returns

Nothing.

endnetent Function ^TOP^

Purpose

Closes the connection to the database, releasing any open file descriptor.

Declared In

posix/netdb.h

Prototype

void endnetent (
   void
)

Parameters

None.

Returns

Nothing.

endprotoent Function ^TOP^

Purpose

Closes the connection to the database, releasing any open file descriptor.

Declared In

posix/netdb.h

Prototype

void endprotoent (
   void
)

Parameters

None.

Returns

Nothing.

endservent Function ^TOP^

Purpose

Closes the connection to the database, releasing any open file descriptor.

Declared In

posix/netdb.h

Prototype

void endservent (
   void
)

Parameters

None.

Returns

Nothing.

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.

Returns

Nothing.

freehostent Function ^TOP^

Purpose

Releases the dynamically allocated memory 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.

Returns

Returns a pointer to an object of the hostent structure.

Compatibility

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.

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.

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.

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.

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 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
)

Parameters

None.

Returns

Returns a pointer to an object of the hostent structure.

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 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 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.

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.

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.

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
)

Parameters

None.

Returns

Returns a pointer to an object of the netent structure, describing the network database.

getpeername Function ^TOP^

Purpose

Gets the name of the connected peer.

Declared In

posix/sys/socket.h

Prototype

int getpeername (
   int sock,
   struct sockaddr *addr,
   socklen_t addrlen
)

Parameters

sock
A socket.
addr
A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
addrlen
Initially contains the amount of space pointed to by addr; on return, it contains the actual length (in bytes) of the address returned.

Returns

Returns the name of the peer connected to the specified socket.

See Also

accept(), bind(), getsockname(), socket()

getsockname Function ^TOP^

Purpose

Gets the socket name.

Declared In

posix/sys/socket.h

Prototype

int getsockname (
   int sock,
   struct sockaddr *addr,
   socklen_t addrlen
)

Parameters

sock
A socket.
addr
A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
addrlen
Initially contains the amount of space pointed to by addr; on return, it contains the actual length (in bytes) of the address returned.

Returns

Returns the current name for the specified socket.

See Also

bind(), socket()

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.

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.

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
)

Parameters

None.

Returns

Returns a pointer to an object of the protoent structure, describing the network database.

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.

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.

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
)

Parameters

None.

Returns

Returns a pointer to an object of the servent structure, describing the network services database.

getsockopt Function ^TOP^

Purpose

Gets the options on sockets.

Declared In

posix/sys/socket.h

Prototype

int getsockopt (
   int sock,
   int level,
   int option,
   void *optval,
   socklen_t *optlen
)

Parameters

sock
A socket.
level
To manipulate options at the socket level, level is specified as SOL_SOCKET.
option
option and any specified options are passed uninterpreted to the appropriate protocol module for interpretation.

Returns

Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

getprotoent(), select(), socket(), setsockopt()

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 a Palm OS extension (not present in C99 or Unix).

htonl Function ^TOP^

Purpose

Converts 32-bit values between host byte order and network byte order.

Declared In

posix/netinet/in.h

Prototype

uint32_t htonl (
   uint32_t host32
)

Parameters

host32
The value being converted.

Returns

Returns an unsigned integer.

See Also

gethostbyname(), getservent()

htons Function ^TOP^

Purpose

Converts 16-bit values between host byte order and network byte order.

Declared In

posix/netinet/in.h

Prototype

uint16_t htons (
   uint16_t host16
)

Parameters

host16
The value being converted.

Returns

Returns an unsigned short integer.

See Also

gethostbyname(), getservent()

inet_addr Function ^TOP^

Purpose

Interprets the specified character string (the name of a computer on the Internet) and returns a number suitable for use as an Internet address.

Declared In

posix/arpa/inet.h

Prototype

in_addr_t inet_addr (
   const char *cp
)

Parameters

cp
A character string indicating the name of a computer on the Internet.

Returns

Returns a number suitable for use as an Internet address.

Comments

The string cp should be a name such as "palmsource.com" or "foo.bar.com".

See Also

inet_network()

inet_aton Function ^TOP^

Purpose

Interprets the specified character string as an Internet address, placing the address into the structure provided.

Declared In

posix/arpa/inet.h

Prototype

int inet_aton (
   const char *cp,
   struct in_addr *addr
)

Parameters

cp
A character string. In order for this function to work successfully, the string must be a standard dotted-quad format IP address, such as "127.0.0.1".
addr
An Internet address.

Returns

Returns 1 if the string was successfully interpreted, or zero (0) if the string is invalid.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

inet_lnaof Function ^TOP^

Purpose

Breaks apart the specified Internet host address and returns the local network address part (in host order).

Declared In

posix/arpa/inet.h

Prototype

in_addr_t inet_lnaof (
   struct in_addr in
)

Parameters

in
An Internet address.

Returns

Returns the local network address (in host order).

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

inet_netof()

inet_makeaddr Function ^TOP^

Purpose

Takes an Internet network number and a local network address (both in host order) and constructs an Internet address from it.

Declared In

posix/arpa/inet.h

Prototype

struct in_addr inet_makeaddr (
   int net,
   int lna
)

Parameters

net
An Internet network number.
lna
A local network address.

Returns

Returns an Internet address.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

inet_netof Function ^TOP^

Purpose

Breaks apart the specified Internet host address and returns the network number part (in host order).

Declared In

posix/arpa/inet.h

Prototype

in_addr_t inet_netof (
   struct in_addr in
)

Parameters

in
An Internet address.

Returns

Returns the network number (in host order).

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

inet_lnaof()

inet_network Function ^TOP^

Purpose

Interprets the specified character string and returns a number suitable for use as an Internet network number.

Declared In

posix/arpa/inet.h

Prototype

in_addr_t inet_network (
   const char *cp
)

Parameters

cp
A character string.

Returns

Returns a number suitable for use as an Internet network number.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

inet_addr()

inet_ntoa Function ^TOP^

Purpose

Takes an Internet address and returns an ASCII string representing the address.

Declared In

posix/arpa/inet.h

Prototype

const char *inet_ntoa (
   struct in_addr in
)

Parameters

in
An Internet address.

Returns

Returns a pointer to an ASCII string representing the address.

inet_ntop Function ^TOP^

Purpose

Converts a network format address to presentation format.

Declared In

posix/arpa/inet.h

Prototype

const char *inet_ntop (
   int af,
   const void *src,
   char *dst,
   size_t size
)

Parameters

af
The address family.
src
The source buffer.
dst
The destination buffer.
size
The size of the destination buffer.

Returns

Returns a pointer to the destination buffer. Otherwise, NULL is returned if a system error occurs and the global variable errno is set to indicate the error.

inet_pton Function ^TOP^

Purpose

Converts a presentation format address to network format.

Declared In

posix/arpa/inet.h

Prototype

int inet_pton (
   int af,
   const char *src,
   void *dst
)

Parameters

af
The address family.
src
The printable form as specified in a character string.
dst
The destination string.

Returns

Returns 1 if the address was valid for the specified address family, or zero (0) if the address was not parseable in the specified address family, or -1 if some system error occurred (in which case the global variable errno is set to indicate the error).

listen Function ^TOP^

Purpose

Listens for connections on a socket.

Declared In

posix/sys/socket.h

Prototype

int listen (
   int sock,
   int backlog
)

Parameters

sock
The socket on which to listen for incoming connection attempts.
backlog
The maximum length the queue of pending connections may grow to.

Returns

Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

accept(), connect(), socket()

ntohl Function ^TOP^

Purpose

Converts 32-bit values between network byte order and host byte order.

Declared In

posix/netinet/in.h

Prototype

uint32_t ntohl (
   uint32_t net32
)

Parameters

net32
The value being converted.

Returns

Returns an unsigned integer.

See Also

gethostbyname(), getservent()

ntohs Function ^TOP^

Purpose

Converts 16-bit values between network byte order and host byte order.

Declared In

posix/netinet/in.h

Prototype

uint16_t ntohs (
   uint16_t net16
)

Parameters

net16
The value being converted.

Returns

Returns an unsigned short integer.

See Also

gethostbyname(), getservent()

recv Function ^TOP^

Purpose

Normally used only on a connected socket and is identical to recvfrom() with a NULL addr parameter.

Declared In

posix/sys/socket.h

Prototype

ssize_t recv (
   int sock,
   void *data,
   size_t datalen,
   int flags
)

Parameters

sock
A socket.
data
The message.
datalen
The length of the message.
flags
ORs together one or more of the values: MSG_OOB, MSG_PEEK, MSG_WAITALL.

Returns

Returns the length of the message upon successful completion. Otherwise, -1 is returned and the global variable errno is set to indicate the error. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from.

See Also

connect(), recvfrom(), recvmsg()

recvfrom Function ^TOP^

Purpose

Receives messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented.

Declared In

posix/sys/socket.h

Prototype

ssize_t recvfrom (
   int sock,
   void *data,
   size_t datalen,
   int flags,
   struct sockaddr *addr,
   socklen_t *addrlen
)

Parameters

sock
A socket.
data
The message.
datalen
The length of the message.
flags
ORs together one or more of the values: MSG_OOB, MSG_PEEK, MSG_WAITALL.
addr
If addr is non-NULL, and the socket is not connection-oriented, the source address of the message is filled in.
addrlen
Initially contains the amount of space pointed to by addr; on return, it contains the actual length (in bytes) of the address stored there.

Returns

Returns the length of the message upon successful completion. Otherwise, -1 is returned and the global variable errno is set to indicate the error. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from.

See Also

connect(), recv(), recvmsg()

recvmsg Function ^TOP^

Purpose

Receives messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented.

Declared In

posix/sys/socket.h

Prototype

ssize_t recvmsg (
   int sd,
   struct msghdr *msg,
   int flags
)

Parameters

sd
A socket.
msg
The message.
flags
ORs together one or more of the values: MSG_OOB, MSG_PEEK, MSG_WAITALL.

Returns

Returns the length of the message upon successful completion. Otherwise, -1 is returned and the global variable errno is set to indicate the error. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from.

See Also

connect(), recv(), recvfrom()

select Function ^TOP^

Purpose

Examines the I/O descriptor sets whose addresses are passed in to see if some of their descriptors are ready.

Declared In

posix/sys/select.h

Prototype

int select (
   int fd,
   fd_set *rfds,
   fd_set *wfds,
   fd_set *efds,
   struct timeval *timeout
)

Parameters

fd
The descriptors are checked in each set; that is, the descriptors from zero (0) through fd - 1 in the descriptor sets are examined.
rfds
The descriptors are checked to see if some of them are ready for reading.
wfds
The descriptors are checked to see if some of them are ready for writing.
efds
The descriptors are checked to see if some of them have an exceptional condition pending.
timeout
If timeout is a non-NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, then select() blocks indefinitely. To affect a poll, the timeout argument should be non-NULL, pointing to a zero-valued timeval structure.

Returns

Returns the number of ready descriptors that are contained in the descriptor sets. Otherwise, -1 is returned and the global variable errno is set to indicate the error. If the time limit expires, select() returns zero (0). If select() returns with an error, including one due to an interrupted call, the descriptor sets are unmodified.

See Also

accept(), connect(), recv(), send()

send Function ^TOP^

Purpose

Sends a message from a socket.

Declared In

posix/sys/socket.h

Prototype

ssize_t send (
   int sock,
   const void *data,
   size_t datalen,
   int flags
)

Parameters

sock
A socket.
data
The message.
datalen
The length of the message.
flags
ORs together one or more of the values: MSG_OOB, MSG_DONTROUTE.

Returns

Returns the number of characters sent. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

Comments

May be used only when the socket is in a connected state.

See Also

select(), sendmsg(), sendto()

sendmsg Function ^TOP^

Purpose

Sends a message from a socket.

Declared In

posix/sys/socket.h

Prototype

ssize_t sendmsg (
   int sd,
   const struct msghdr *msg,
   int flags
)

Parameters

sd
A socket.
msg
The message.
flags
ORs together one or more of the values: MSG_OOB, MSG_DONTROUTE.

Returns

Returns the number of characters sent. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

select(), send(), sendto()

sendto Function ^TOP^

Purpose

Sends a message from a socket.

Declared In

posix/sys/socket.h

Prototype

ssize_t sendto (
   int sock,
   const void *data,
   size_t datalen,
   int flags,
   const struct sockaddr *addr,
   socklen_t addrlen
)

Parameters

sock
A socket.
data
The message.
datalen
The length of the message.
flags
ORs together one or more of the values: MSG_OOB, MSG_DONTROUTE.
addr
If addr is non-NULL, and the socket is not connection-oriented, the source address of the message is filled in.
addrlen
Initially contains the amount of space pointed to by addr; on return, it contains the actual length (in bytes) of the address stored there.

Returns

Returns the number of characters sent. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

select(), send(), sendmsg()

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.

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

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

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

See Also

getservbyname(), getservbyport()

setsockopt Function ^TOP^

Purpose

Sets options on sockets.

Declared In

posix/sys/socket.h

Prototype

int setsockopt (
   int sock,
   int level,
   int option,
   const void *optval,
   socklen_t optlen
)

Parameters

sock
A socket.
level
To manipulate options at the socket level, level is specified as SOL_SOCKET.
option
Any specified option(s) passed uninterpreted to the appropriate protocol module for interpretation.
optval
Used to access option values. Identifies a buffer in which the value for the requested option is returned.
optlen
Used to access option values. Identifies a buffer in which the length for the requested option is returned.

Returns

Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

getprotoent(), getsockopt(), select(), socket()

shutdown Function ^TOP^

Purpose

Disables subsequent send and/or receive operations on a socket.

Declared In

posix/sys/socket.h

Prototype

int shutdown (
   int sock,
   int direction
)

Parameters

sock
A socket.
direction
Specifies the type of shutdown. The values are as follows:
SHUT_RD
Disables further receive operations.
SHUT_WR
Disables further send operations.
SHUT_RDWR
Disables further send and receive operations.

Returns

Returns zero (0) upon successful completion. Otherwise, 1 is returned and the global variable errno is set to indicate the error.

socket Function ^TOP^

Purpose

Creates an endpoint for communication.

Declared In

posix/sys/socket.h

Prototype

int socket (
   int family,
   int type,
   int proto
)

Parameters

family
A communications domain within which communication takes place; this selects the protocol family that should be used.
type
The semantics of communication.
proto
A particular protocol to be used with the socket.

Returns

Returns a descriptor referencing the socket. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

See Also

getsockopt()