|
The TCP/IP stack supports a subset of standard Berkeley sockets, in particular, only blocking sockets can be used in this implementation.
Only those functions which differ from standard Berkeley sockets are described in depth.
All of the functions and constants are defined in the socket.h header file which is automatically included when you include stack.h.
You can find socket.h in <3L>\Diamond\edition\Sundance\C6000\include\TCP_IP_include
socket
int socket(int family,
int type,
int protocol);
|
|
The socket function creates a socket that is bound to a specific transport service provider.
Parameters
family
specifies the protocol family of the created socket.
The only supported value is AF_INET (Ipv4 protocol family)
type
Supported: SOCK_STREAM – reliable stream-oriented service (TCP)
SOCK_DGRAM – unreliable datagram service (UDP)
SOCK_RAW – raw protocols
protocol
Supported: IPPROTO_TCP – TCP protocol
IPPROTO_UDP – UDP protocol
Return value
socket returns a descriptor referencing the new socket if no error occurs, otherwise it returns -1 and sets errno to indicate the error.
|
|
connect
int connect(int socket,
const struct sockaddr *serverAddr,
int addrLen);
|
|
The meaning of connect differs according to the type of socket specified by the socket argument .
If the given socket belongs to a connection-oriented protocol (TCP), connect attempts to establish a connection to the address specified by the address argument.
If the socket belongs to connection-less protocol (UDP), the socket's peer address is set, but no connection is made. For SOCK_DGRAM sockets, the peer address identifies where all datagrams are sent on subsequent send() calls, and limits the remote sender for subsequent recv() calls.
Parameters
socket
A descriptor identifying an unbound socket.
serverAddr
Points to a sockaddr structure containing the peer address.
addrLen
Specifies the length of the sockaddr structure pointed to by serverAddr
Return value
connectreturns 0 if no error occurs, otherwise it returns -1 and sets errno to indicate the error.
|
|
bind
int bind(int socket,
const struct sockaddr *myAddr,
int addrLen);
|
|
bind assigns a local socket address, specified by myAddr, to a socket identified by socket that has no local socket address assigned. Sockets created with the socket function are initialy unnamed.
Parameters
socket
A descriptor identifying an unbound socket.
myAddr
Points to a sockaddr structure containing the address to be bound to the socket.
addrLen
Specifies the length of the sockaddr structure pointed to by myAddr.
Return values
bind returns 0 if no error occurs, otherwise it returns -1 and sets errno to indicate the error.
|
|
listen
int listen(int socket,
int backlog);
|
|
listen prepares a bound connection-oriented socket to accept incoming connections.
Parameters
socket
A descriptor identifying an unbound socket.
backlog
Limits the number of outstanding connections in the socket's listen queue.
Return value
listen returns 0 if no error occurs, otherwise it returns -1 and sets errno to indicate the error.
|
|
accept
int accept(int socket,
struct sockaddr *addr,
int *addrLen);
|
|
accept accepts a connection request from a remote host. If addr is not a null pointer, the address of the peer for the accepted connection is stored in the sockaddr structure pointed to by addr, and the length of this address is stored through addrLen.
Parameters
socket
Specifies a socket that was created with socket, has been bound to an address with bind and has issued a successful call to listen.
addr
Either a null pointer, or a pointer to a sockaddr structure where the address of the connecting socket is returned.
addrLen
Points to an int variable which on input specifies the length of the supplied sockaddr structure, and on output receives the length of the stored address.
Return value
accept returns the non-negative descriptor of the accepted socket if , otherwise it returns -1 and sets errno to indicate the error.
|
|
recv
ssize_t recv(int socket,
void *buf,
size_t len,
int flags);
|
|
recv receives a message from a connection-oriented or connection-less socket. It is normally used with connected sockets because it does not allow the application to retrieve the source address of received data. recv blocks until data is available, the connection is closed by peer, or an error occurs.
For message-based sockets, SOCK_DGRAM, the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer, and MSG_PEEK is not set in the flags argument, the excess bytes are discarded. For stream based sockets, SOCK_STREAM, message boundaries are ignored; data are returned to the user as soon as they become available and no data are discarded.
Parameters
socket
Specifies the socket descriptor.
buf
Points to a buffer where the message will be stored.
len
Specifies the length in bytes of the buffer pointed to by buf.
flags
Specifies the type of message reception. Values of this argument are 0 or a combination (|) of one or more of the following:
MSG_PEEK
Peeks at an incoming message. The data are treated as unread and the next recv or equivalent function will still return this data.
MSG_OOB
Requests out-of-band data. The significance and semantics of out-of-band data are protocol-specific.
MSG_WAITALL
On SOCK_STREAM sockets this requests that the function should block until the full amount of data can be returned. This function may return a smaller amount of data if the socket is a message-based socket, if the connection is terminated, if MSG_PEEK was specified, or if an error is pending for the socket.
Return value
recv returns the length of the message in bytes. If no messages are available to be received and the peer has performed an orderly shutdown, recv returns 0. It returns -1 to indicate a failure and sets errno to indicate the error.
|
|
recvfrom
ssize_t recvfrom(int socket,
void *buf,
size_t len,
int flags,
struct sockaddr *addr,
int *addrLen);
|
|
recvfrom receives a message from a connection-oriented or connection-less socket. It is normally used with conection-less sockets because it permits the application to retrieve the source address of received data.
recvfrom blocks until data is available, the connection is closed by peer, or an error occurs.
For message-based sockets, SOCK_DGRAM, the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer and MSG_PEEK is not set in the flags argument, the excess bytes are discarded. For stream based sockets SOCK_STREAM, message boundaries are ignored; data are returned to the user as soon as they become available and no data are discarded.
Parameters
socket
specifies the socket descriptor.
buf
points to the buffer where the message shall be stored.
len
specifies the length in bytes of the buffer pointed to by buf.
flags
specifies the type of message reception. Values of this argument are 0 or a combination (|) of one or more of the following:
MSG_PEEK
peeks at an incoming message. The data are treated as unread and the next recv or equivalent function will still return this data.
MSG_OOB
Requests out-of-band data. The significance and semantics of out-of-band data are protocol-specific.
MSG_WAITALL
On SOCK_STREAM sockets this requests that the function should block until the full amount of data can be returned. This function may return a smaller amount of data if the socket is message-based, if the connection is terminated, if MSG_PEEK was specified, or if an error is pending for the socket.
addr
is a null pointer, or points to a sockaddr structure in which the sending address is to be stored. The length and format of the address depend on the address family of the socket.
addrLen
specifies the length of the sockaddr structure pointed to by addr.
Return values
recvfrom returns the length of the message in bytes or, if no messages are available to be received and the peer has performed an orderly shutdown, it returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
rcvmsg
ssize_t recvmsg(int socket,
struct msghdr *msg,
int flags);
|
|
recvmsg receives a message from a connection-oriented or connection-less socket. It is normally used with connection-less sockets because it permits the application to retrieve the source address of the received data. It returns the length of the message.
For message-based sockets, such as SOCK_DGRAM, the entire message is read in a single operation. If a message is too long to fit in the supplied buffers, and MSG_PEEK is not set in the flags argument, the excess bytes are discarded, and MSG_TRUNC is set in the msg_flags member of msghdr. For stream-based sockets, such as SOCK_STREAM, message boundaries are ignored. In this case, data are returned to the user as soon as they become available, and no data are discarded.
If the MSG_WAITALL flag is not set, data are returned only up to the end of the first message.
In the msghdr structure, the msg_name and msg_namelen members specify the source address if the socket is unconnected; if the socket is connected, they are ignored. The msg_name member may be a null pointer if no names are desired or required. The msg_iov and msg_iovlen fields are used to specify where the received data will be stored. msg_iov points to an array of iovec structures and msg_iovlen is set to number of elements in this array. In each iovec structure, iov_base specifies a storage area and iov_len gives its size in bytes. Each storage area indicated by msg_iov is filled with received data in turn until all of the received data are stored or all of the areas have been filled.
Parameters
socket
specifies the socket descriptor.
msg
points to a msghdr structure, containing both the buffer to store the source address and the buffers for the incoming message. The length and format of the address depend on the address family of the socket. The msg_flags member is ignored on input, but may contain meaningful values on output.
flags
specifies the type of message reception. Values of this argument are 0 or a combination (|) of one or more of the following:
MSG_PEEK
peeks at an incoming message. The data are treated as unread and the next recv or equivalent function will still return this data.
MSG_OOB
requests out-of-band data. The significance and semantics of out-of-band data are protocol-specific.
MSG_WAITALL
On SOCK_STREAM sockets this requests that the function block until the full amount of data can be returned. This function may return a smaller amount of data if the socket is message-based, if the
connection is terminated, if MSG_PEEK was specified, or if an error is pending for the socket.
Return value
recvmsg returns the length of the message in bytes or, if no messages are available to be received and the peer has performed an orderly shutdown, it returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
send
ssize_t send(int socket,
const void *buf,
size_t len,
int flags);
|
|
send initiates transmission of a message from the specified socket to its peer. It sends a message only when the socket is connected (including when the peer of a socket has been set via connect). The length of the message to be sent is specified by len argument. If the message is too long to pass through the underlying protocol, send fails and no data are transmitted.
Successful completion of a call to send does not guarantee delivery of the message. A return value of -1 indicates only locally-detected errors.
If space is not available at the sending socket to hold the message to be transmitted, send blocks until space is available.
Parameters
socket
specifies the socket descriptor.
buf
points to the buffer containing the message to send.
len
specifies the length of message in bytes.
flags
specifies the type of message transmission. Values of this argument are 0 or a combination (|) of one or more of the following:
MSG_OOB
sends out-of-band data in sockets that support out of band communications. The significance and semantics of out-of band data are protocol-specific.
MSG_EOR
terminates a record (if supported by the protocol).
Return value
Upon successful completion, send returns the number of bytes sent, otherwise it returns -1 and sets errno to indicate the error.
|
|
setnto
ssize_t sendto(int socket,
const void *buf,
size_t len,
int flags,
const struct sockaddr *addr,
int addrLen);
|
|
sendto sends a message through a connection-oriented or connection-less socket. If the socket is connection-less, the message is sent to the address specified by addr; if it is connection-oriented, addr is ignored.
The length of the message to be sent is specified by len. If the message is too long to pass through the underlying protocol, send fails and no data are transmitted.
Successful completion of a call to send does not guarantee delivery of the message. A return value of -1 indicates only locally-detected errors.
If space is not available at the sending socket to hold the message to be transmitted, send blocks until space is available.
If the socket protocol supports broadcast and the specified address is a broadcast address for the socket protocol, sendto fails if the SO_BROADCAST option is not set for the socket.
Parameters
socket
Specifies the socket descriptor.
buf
Points to the buffer containing the message to send.
len
Specifies the length of message in bytes.
flags
specifies the type of message transmission. Values of this argument are 0 or a combination (|) of one or more of the following:
MSG_OOB
sends out-of-band data in sockets that support out of band communications. The significance and semantics of out-of band data are protocol-specific.
MSG_EOR
terminates a record (if supported by the protocol).
addr
points to a sockaddr structure containing the destination address. The length and format of the address depend on the address family of the socket.
addrlen
specifies the length of the sockaddr structure pointed to by addr.
Return value
Upon successful completion, sendto returns the number of bytes sent, otherwise it returns -1 and sets errno to indicate the error.
|
|
sendmsg
ssize_t sendmsg(int socket,
const struct msghdr *msg,
int flags);
|
|
sendmsg sends a message through a connection-oriented or connection-less socket. If the socket is connection-less, the message is sent to the address specified by msghdr; if it is connection-oriented, msghdr is ignored.
Parameters
socket
specifies the socket descriptor.
msg
points to a msghdr structure, containing both the destination address and the buffers for the outgoing message. The length and format of the address depend on the address family of the socket. The msg_flags member is ignored.
flags
specifies the type of message transmission. Values of this argument are 0 or a combination (|) of one or more of the following:
MSG_OOB
sends out-of-band data in sockets that support out of band communications. The significance and semantics of out-of band data are protocol-specific.
MSG_EOR
terminates a record (if supported by the protocol).
Return value
Upon successful completion, sendmsg returns the number of bytes sent, otherwise it returns -1 and sets errno to indicate the error.
|
|
shutdown
int shutdown(int socket,
int how);
|
|
shutdown function causes all or part of a full-duplex connection on the socket associated with the descriptor socket to be shut down. It disables subsequent send or receive operations on a socket depending on the value of the how argument.
Parameters
socket
specifies the descriptor of the socket.
how
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 or receive operations
Return value
Upon successful completion shutdown returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
closesocket
int closesocket(int socket);
|
|
closesocket closes a connection and returns the socket to the system.
Parameter
socket
identifies the socket to close.
Return value
Upon successful completion closesocket returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
setsockopt
int setsockopt(int socket,
int level,
int option_name,
const void *option_value,
int option_len);
|
|
setsockop sets the option selected by option_name at the protocol level specified by level to the value pointed to by option_value for the socket identified by socket.
option_name and any specified options are passed without interpretation to the appropriate protocol module.
Parameters
socket
specifies the descriptor of the socket.
level
specifies the protocol level at which the option resides. To set options at the socket level, specify the level as SOL_SOCKET. To set options at other levels, supply the appropriate level identifier for the protocol controlling the option (for example IPPROTO_TCP for TCP protocol).
option_name
specifies a single option to set. socket.h defines the socket-level options as follows:
SO_BROADCAST
permits sending broadcast messages, if this is supported by the protocol. This is a Boolean option taking an int value of 0 (disabled) or 1 (enabled).
SO_REUSEADDR
specifies that the rules used in validating addresses supplied to bind should allow reuse of local addresses, if this is supported by the protocol. This is a Boolean option taking an int value of 0 (disabled) or 1 (enabled).
SO_KEEPALIVE
keeps connections active by enabling the periodic transmission of messages, if this is supported by the protocol. The connection is broken if the connected socket fails to respond to these messages. This is a Boolean option taking an int value of 0 (disabled) or 1 (enabled).
SO_LINGER
lingers on a closesocket call if data is present. This option controls the action taken when unsent messages queue on a socket and closesocket is performed. If SO_LINGER is set, the system blocks the calling thread during closesocket until it can transmit the data or until the time expires. If SO_LINGER is not specified when closesocket is issued, the system handles the call in a way that allows the calling thread to continue as quickly as possible. This option takes a linger structure, as defined in socket.h, to specify the state of the option and the linger interval.
SO_OOBINLINE
leaves received out-of-band data (data marked urgent) inline. This is a Boolean option taking an int value of 0 (disabled) or 1 (enabled).
SO_SNDBUF
sets the send buffer size. It takes an int value.
SO_RCVBUF
sets the receive buffer size. It takes an int value.
SO_DONTROUTE
requests that outgoing messages bypass the standard routing facilities. The destination must be on a directly-connected network, and messages are directed to the appropriate network interface according to the destination address. The effect, if any, of this option depends on what protocol is in use. This is a Boolean option taking an int value of 0 (disabled) or 1 (enabled).
SO_RCVLOWAT
sets the minimum number of bytes to process for socket input operations. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. (They may return less than the low water mark if an error occurs, or the type of data next in the receive queue is different from that returned; for example, out-of-band data.) This option takes an int value.
SO_RCVTIMEO
sets the timeout value that specifies the maximum amount of time an input function waits until it completes. It accepts a timeval structure with the number of seconds and microseconds specifying the limit on how long to wait for an input operation to complete. If a receive operation has blocked for this much time without receiving additional data, it will return with a partial count or errno set to EAGAIN or EWOULDBLOCK if no data is received. The default for this option is zero, which indicates that a receive operation will not time out. This option takes a timeval structure.
SO_SNDLOWAT
sets the minimum number of bytes to process for socket output operations. Non-blocking output operations will process no data if flow control does not allow the smaller of the send low water mark value or the entire request to be processed. This option takes an int value.
SO_SNDTIMEO
sets the timeout value specifying the amount of time that an output function blocks because flow control prevents data from being sent. If a send operation has blocked for this time, it will return with a partial count or with errno set to[EAGAIN or EWOULDBLOCK if no data is sent. The default for this option is zero, which indicates that a send operation will not time out. This option stores a timeval structure.
option_value
points to an object to be passed as value for given option. For Boolean options, 0 indicates that the option is disabled and 1 indicates that the option is enabled.
option_len
specifies the length in bytes of the object pointed to by the option_value argument.
Return value
Upon successful completion setsockopt returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
getsockopt
int getsockopt(int socket,
int level,
int option_name,
void *option_value,
int *option_len);
|
|
getsockopt retrieves the value for the option specified by option_name for the socket specified by socket. If the size of the option value is greater than option_len, the value stored in the object pointed to by option_value is silently truncated; otherwise, the object pointed to by option_len is modified to indicate the actual length of the value.
Parameters
socket
specifies the descriptor of the socket.
level
specifies the protocol level at which the option resides. To retrieve options at the socket level specify level as SOL_SOCKET. To retrieve options at other levels, supply the appropriate level identifier for the protocol controlling the option (for example IPPROTO_TCP for TCP protocol).
option_name
specifies a single option to be retrieved. The socket.h header defines the socket-level options. The options are as follows:
SO_ACCEPTCONN
reports whether socket listening is enabled. This is a Boolean option storing an int value of 0 (disabled) or 1 (enabled).
SO_BROADCAST
reports whether transmission of broadcast messages is supported by the protocol. This is a Boolean option storing an int value of 0 (disabled) or 1 (enabled).
SO_REUSEADDR
reports whether the rules used in validating addresses supplied to bind allows reuse of local addresses, if this is supported by the protocol. This is a Boolean option storing an int value of 0 (disabled) or 1 (enabled).
SO_KEEPALIVE
reports whether connections are kept active with periodic transmission of messages, if this is supported by the protocol. The connection is broken if the connected socket fails to respond to these messages. This is a Boolean option storing an int value of 0 (disabled) or 1 (enabled).
SO_LINGER
reports whether the socket lingers on closesocket if data is present. If SO_LINGER is set, the system blocks the calling thread during closesocket until it can transmit the data or until the end of the interval indicated by the l_linger member, whichever comes first. If SO_LINGER is not specified, and closesocket is issued, the system handles the call in a way that allows the calling thread to continue as quickly as possible. This option stores a linger structure.
SO_OOBINLINE
reports whether the socket leaves received out-of-band data (data marked urgent) inline. This is a Boolean option storing an int value of 0 (disabled) or 1 (enabled).
SO_SNDBUF
reports send buffer size information. This option stores an int value.
SO_RCVBUF
reports receive buffer size information. This option stores an int value..
SO_ERROR
reports information about error status and clears it. This option stores an int value.
SO_TYPE
reports the socket type. This option stores an int value.
SO_DONTROUTE
reports whether outgoing messages bypass the standard routing facilities. The destination will be on a directly-connected network, and messages are directed to the appropriate network interface according to the destination address. The effect, if any, of this option depends on what protocol is in use. This is a Boolean option storing an int value of 0 (disabled) or 1 (enabled).
SO_RCVLOWAT
reports the minimum number of bytes to process for socket input operations. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. They may return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different from that returned; for example, out-of-band data. This option stores an int value.
SO_RCVTIMEO
reports the timeout value for input operations. This option stores a timeval structure with the number of seconds and microseconds specifying the limit on how long to wait for an input operation to complete. If a receive operation has blocked for this much time without receiving additional data, it returns with a partial count or errno set to EAGAIN or EWOULDBLOCK if no data was received. The default for this option is zero, which indicates that a receive operation will not time out.
SO_SNDLOWAT
reports the minimum number of bytes to process for socket output operations. Non-blocking output operations process no data if flow control does not allow the smaller of the send low water mark value or the entire request to be processed. This option stores an int value.
SO_SNDTIMEO
reports the timeout value specifying the amount of time that an output function blocks because flow control prevents data from being sent. If a send operation has blocked for this time, it returns with a partial count or with errno set to EAGAIN or EWOULDBLOCK if no data was sent. The default for this option is zero, which indicates that a send operation will not time out. The option stores a timeval structure.
option_value
points to an object the option value shall be stored in. For Boolean options, 0 indicates that the option is disabled and 1 indicates that the option is enabled.
option_len
specifies the length in bytes of the retrieved value.
Return value
Upon successful completion, getsockopt returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
getpeername
int getpeername(int socket,
struct sockaddr *peerAddr,
int *addrLen);
|
|
getpeername retrieves the peer address of the specified socket, stores this address in the sockaddr structure pointed to by peerAddr, and stores the length of this address in the object pointed to by addrLen. If the actual length of the address is greater than the length of the supplied sockaddr structure, the stored address will be truncated. If the protocol permits connections by unbound clients, and the peer is not bound, then the value stored in the object pointed to by peerAddr is unspecified.
Parameters
socket
specifies the descriptor of the socket.
peerAddr
points to where a sockaddr structure will be stored.
addrLen
points to an object that on input specifies the length in bytes of an area reserved for a sockaddr structure, and on output receives the actual size of the stored sockaddr structure.
Return value
Upon successful completion, getpeername returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
getsockname
int getsockname(int socket,
struct sockaddr *localAddr,
int *addrLen);
|
|
getsockname retrieves the locally-bound name of the specified socket, stores this address in the sockaddr structure pointed to by localAddr, and stores the length of this address in the object pointed to by addrLen.
If the actual length of the address is greater than the length of the supplied sockaddr structure, the stored address will be truncated. If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.
Parameters
socket
specifies the descriptor of the socket.
peerAddr
points to memory where a sockaddr structure will be stored.
addrLen
points to an object that on input specifies the length in bytes of an area reserved for a sockaddr structure, and on output receives the actual size of the stored sockaddr structure.
Return value
Upon successful completion, getsockname returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
socketpair
int socketpair(int domain,
int type,
int protocol,
int *socket_vector);
|
|
socketpair creates an unbound pair of connected sockets in a specified domain, of a specified type, under the protocol optionally specified by protocol. The two sockets will be identical. The file descriptors used in referencing the created sockets will be returned in socket_vector[0] and socket_vector[1].
Parameters
domain
specifies the communications domain in which the sockets are to be created.
type
specifies the type of sockets to be created.
protocol
specifies a particular protocol to be used with the sockets. Specifying a protocol of 0 causes socketpair to use an unspecified default protocol appropriate for the requested socket type.
socket_vector
specifies an array of two intergers to hold the file descriptors of the created socket pair.
Return value
Upon successful completion, socketpair returns 0, otherwise it returns -1 and sets errno to indicate the error.
|
|
|