Overview
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
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).
sockaddr Struct
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
sockaddr_in Struct
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
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
accept Function
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 ( intsock
, struct sockaddr *addr
, socklen_t *addrlen
)
Parameters
-
→ sock
- A socket that has been created with
socket()
, bound to an address withbind()
, and listening for connections after alisten()
. -
← 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
Purpose
Assigns a name to an unnamed socket.
Declared In
posix/sys/socket.h
Prototype
int bind ( intsock
, const struct sockaddr *addr
, socklen_taddrlen
)
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
Purpose
Initiates a connection on a socket.
Declared In
posix/sys/socket.h
Prototype
int connect ( intsock
, const struct sockaddr *addr
, socklen_taddrlen
)
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
Purpose
Declared In
posix/netdb.h
Prototype
void endhostent ( void )
Parameters
Returns
endnetent Function
Purpose
Closes the connection to the database, releasing any open file descriptor.
Declared In
posix/netdb.h
Prototype
void endnetent ( void )
Parameters
Returns
endprotoent Function
Purpose
Closes the connection to the database, releasing any open file descriptor.
Declared In
posix/netdb.h
Prototype
void endprotoent ( void )
Parameters
Returns
endservent Function
Purpose
Closes the connection to the database, releasing any open file descriptor.
Declared In
posix/netdb.h
Prototype
void endservent ( void )
Parameters
Returns
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.
Returns
freehostent Function
Purpose
Releases the dynamically allocated memory of the hostent
structure.
Declared In
posix/netdb.h
Prototype
void freehostent (
struct hostent *ip
)
Parameters
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
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.
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.
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.
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.
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 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 )
Parameters
Returns
Returns a pointer to an object of the hostent
structure.
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 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 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.
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.
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.
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 )
Parameters
Returns
Returns a pointer to an object of the netent
structure, describing the network database.
getpeername Function
Purpose
Gets the name of the connected peer.
Declared In
posix/sys/socket.h
Prototype
int getpeername ( intsock
, struct sockaddr *addr
, socklen_taddrlen
)
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
Purpose
Declared In
posix/sys/socket.h
Prototype
int getsockname ( intsock
, struct sockaddr *addr
, socklen_taddrlen
)
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
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.
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.
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 )
Parameters
Returns
Returns a pointer to an object of the protoent
structure, describing the network database.
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.
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.
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 )
Parameters
Returns
Returns a pointer to an object of the servent
structure, describing the network services database.
getsockopt Function
Purpose
Declared In
posix/sys/socket.h
Prototype
int getsockopt ( intsock
, intlevel
, intoption
, void *optval
, socklen_t *optlen
)
Parameters
-
→ sock
- A socket.
-
→ level
- To manipulate options at the socket level,
level
is specified asSOL_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
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 a Palm OS extension (not present in C99 or Unix).
htonl Function
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
Returns
See Also
htons Function
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
Returns
Returns an unsigned short integer.
See Also
inet_addr Function
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
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_aton Function
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
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
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_makeaddr Function
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 ( intnet
, intlna
)
Parameters
Returns
Compatibility
This function is a Palm OS extension (not present in C99 or Unix).
inet_netof Function
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
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_network Function
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
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_ntoa Function
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
Returns
Returns a pointer to an ASCII string representing the address.
inet_ntop Function
Purpose
Converts a network format address to presentation format.
Declared In
posix/arpa/inet.h
Prototype
const char *inet_ntop ( intaf
, const void *src
, char *dst
, size_tsize
)
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
Purpose
Converts a presentation format address to network format.
Declared In
posix/arpa/inet.h
Prototype
int inet_pton ( intaf
, 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
Purpose
Listens for connections on a socket.
Declared In
posix/sys/socket.h
Prototype
int listen ( intsock
, intbacklog
)
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
ntohl Function
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
Returns
See Also
ntohs Function
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
Returns
Returns an unsigned short integer.
See Also
recv Function
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 ( intsock
, void *data
, size_tdatalen
, intflags
)
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
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 ( intsock
, void *data
, size_tdatalen
, intflags
, 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
recvmsg Function
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 ( intsd
, struct msghdr *msg
, intflags
)
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
select Function
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 ( intfd
, 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. Iftimeout
is aNULL
pointer, thenselect()
blocks indefinitely. To affect a poll, thetimeout
argument should be non-NULL
, pointing to a zero-valuedtimeval
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
Purpose
Sends a message from a socket.
Declared In
posix/sys/socket.h
Prototype
ssize_t send ( intsock
, const void *data
, size_tdatalen
, intflags
)
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
sendmsg Function
Purpose
Sends a message from a socket.
Declared In
posix/sys/socket.h
Prototype
ssize_t sendmsg ( intsd
, const struct msghdr *msg
, intflags
)
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
sendto Function
Purpose
Sends a message from a socket.
Declared In
posix/sys/socket.h
Prototype
ssize_t sendto ( intsock
, const void *data
, size_tdatalen
, intflags
, const struct sockaddr *addr
, socklen_taddrlen
)
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
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.
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()
.
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()
.
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()
.
See Also
getservbyname()
, getservbyport()
setsockopt Function
Purpose
Declared In
posix/sys/socket.h
Prototype
int setsockopt ( intsock
, intlevel
, intoption
, const void *optval
, socklen_toptlen
)
Parameters
-
→ sock
- A socket.
-
→ level
- To manipulate options at the socket level,
level
is specified asSOL_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
Purpose
Disables subsequent send and/or receive operations on a socket.
Declared In
posix/sys/socket.h
Prototype
int shutdown ( intsock
, intdirection
)
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
Purpose
Creates an endpoint for communication.
Declared In
posix/sys/socket.h
Prototype
int socket ( intfamily
, inttype
, intproto
)
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.