![]() |
Network Component
Version 7.8.0
MDK Middleware for IPv4 and IPv6 Networking
|
BSD Socket functions and communication flow. More...
Functions | |
int | socket (int family, int type, int protocol) |
Create a communication endpoint called socket. [thread-safe]. More... | |
int | bind (int sock, const SOCKADDR *addr, int addrlen) |
Assign a local address and port to a socket. [thread-safe]. More... | |
int | listen (int sock, int backlog) |
Set a socket in a listening mode. [thread-safe]. More... | |
int | accept (int sock, SOCKADDR *addr, int *addrlen) |
Accept connect request for a listening socket. [thread-safe]. More... | |
int | connect (int sock, const SOCKADDR *addr, int addrlen) |
Connect a socket to a remote host. [thread-safe]. More... | |
int | send (int sock, const char *buf, int len, int flags) |
Send data on already connected socket. [thread-safe]. More... | |
int | sendto (int sock, const char *buf, int len, int flags, const SOCKADDR *to, int tolen) |
Send data to endpoint node. [thread-safe]. More... | |
int | recv (int sock, char *buf, int len, int flags) |
Receive data on already connected socket. [thread-safe]. More... | |
int | recvfrom (int sock, char *buf, int len, int flags, SOCKADDR *from, int *fromlen) |
Receive data from endpoint node. [thread-safe]. More... | |
int | closesocket (int sock) |
Close socket and release socket descriptor. [thread-safe]. More... | |
int | getpeername (int sock, SOCKADDR *name, int *namelen) |
Retrieve IP address and port number of the endpoint node. [thread-safe]. More... | |
int | getsockname (int sock, SOCKADDR *name, int *namelen) |
Retrieve local IP address and port number. [thread-safe]. More... | |
int | ioctlsocket (int sock, long cmd, unsigned long *argp) |
Control IO mode of a socket. [thread-safe]. More... | |
int | setsockopt (int sock, int level, int optname, const char *optval, int optlen) |
Manipulate options for the socket. [thread-safe]. More... | |
HOSTENT * | gethostbyname (const char *name, int *err) |
Retrieve host IP address from host name. [thread-safe]. More... | |
BSD Socket functions and communication flow.
The following table shows the available API functions for BSD sockets.
Function | Description |
---|---|
accept | Accepts a connection request queued for a listening socket. |
bind | Assigns a name (local address) to a socket. |
closesocket | Closes an existing socket and releases a socket descriptor. |
connect | Establishes connection between the endpoints on stream sockets. |
gethostbyname | Retrieves host address corresponding to a host name from a host database. |
getpeername | Retrieves the address of the peer to which a socket is connected. |
getsockname | Retrieves the local address of the socket. |
ioctlsocket | Sets or retrieves some of the operating parameters on a socket. |
listen | Sets the socket in a listen mode. |
recv | Receives incoming data that has been queued for a socket. |
recvfrom | Receives incoming data on a datagram socket. |
send | Sends outgoing data on a socket. |
sendto | Sends outgoing data on a datagram socket to destination address. |
setsockopt | Manipulate options for the socket. |
socket | Creates a communication socket. |
The image below explains the basic communication flow using BSD sockets with TCP.
The BSD server creates a socket, uses bind to attach that socket to a port, and configures it as a listening socket. This allows the server to receive incoming connection requests. Afterwards, accept is called, which will block the socket, until an incoming connection request is received. When accept returns, the SOCKADDR structure will have been filled out with the originating IP Address and port of the incoming connection. Then, accept creates a new socket, which is then used to receive data until the connection is closed by the other side.
Code Example
The BSD Client creates a socket calls connect, because TCP requires a negotiated connection. Afterwards, send is called to send the data to the server. Note that bind is never called, because the stack will pick a random port and an appropriate IP address. To finish the communication, the client calls closesocket.
Code Example
int accept | ( | int | sock, |
SOCKADDR * | addr, | ||
int * | addrlen | ||
) |
Accept connect request for a listening socket. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[out] | addr | structure that will receive IP address and port number.
|
[in] | addrlen | length of SOCKADDR structure. |
The function accept accepts a connection request queued for a listening socket. If a connection request is pending, accept removes the request from the queue, and a new socket is created for the connection. The original listening socket remains open and continues to queue new connection requests. The socket sock must be a SOCK_STREAM type socket.
In blocking mode, which is enabled by default in RTOS environment, this functions waits for a connection request. In non blocking mode, you must call the accept function again if the error code BSD_ERROR_WOULDBLOCK is returned.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument addr is a pointer to the SOCKADDR structure that will receive the connection node IP address and port number.
The argument addrlen is a pointer to the address length. It should initially contain the amount of space pointed to by addr. On return it contains the actual length of the address returned in bytes.
Code Example
int bind | ( | int | sock, |
const SOCKADDR * | addr, | ||
int | addrlen | ||
) |
Assign a local address and port to a socket. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[in] | addr | structure containing local IP address and port. |
[in] | addrlen | length of SOCKADDR structure. |
The function bind assigns a name to an unnamed socket. The name represents the local address and port of the communication end point.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument addr is a pointer to the SOCKADDR structure containing the local address and port of the socket.
The argument addrlen specifies the length of the SOCKADDR structure.
Code Example
int closesocket | ( | int | sock | ) |
Close socket and release socket descriptor. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
The function closesocket closes an existing socket and releases the socket descriptor. Further references to sock fail with BSD_ERROR_SOCKET error code.
The argument sock specifies a socket descriptor returned from a previous call to socket.
In blocking mode, which is enabled by default in RTOS environment, this functions will wait until a socket is closed. In non blocking mode, you must call the closesocket function again if the error code BSD_ERROR_WOULDBLOCK is returned.
Code Example
int connect | ( | int | sock, |
const SOCKADDR * | addr, | ||
int | addrlen | ||
) |
Connect a socket to a remote host. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[in] | addr | structure containing remote IP address and port. |
[in] | addrlen | length of SOCKADDR structure. |
The function connect assigns the address of the peer communication end point. For SOCK_STREAM type socket, a connection is established between the end points. For SOCK_DGRAM type socket, an address filter is established between the end points. The address filter is changed with another connect function.
In blocking mode, which is enabled by default in RTOS environment, this functions waits for a connection to be established. In non blocking mode, you must call the connect function again if the error code BSD_ERROR_WOULDBLOCK
is returned.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument addr is a pointer to the SOCKADDR
structure that contains the end point node IP address and port number.
The argument addrlen specifies the length of SOCKADDR structure.
Code Example
HOSTENT * gethostbyname | ( | const char * | name, |
int * | err | ||
) |
Retrieve host IP address from host name. [thread-safe].
[in] | name | host name. |
[out] | err | pointer to where to return error code (NULL for none):
|
The function gethostbyname retrieves host information corresponding to a host name from a host database.
The argument name is a pointer to the null-terminated name of the host to resolve.
The argument err is a pointer to the return error code.
Code Example
int getpeername | ( | int | sock, |
SOCKADDR * | name, | ||
int * | namelen | ||
) |
Retrieve IP address and port number of the endpoint node. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[out] | name | structure that will receive IP address and port number. |
[out] | namelen | length of SOCKADDR structure. |
The function getpeername retrieves the address of the peer to which a socket is connected.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument name is a pointer to the SOCKADDR structure. If name is not NULL, the remote end IP address and port number is filled in.
The argument namelen is a pointer to the address length. It should initially contain the amount of space pointed to by name. On return it contains the actual length of the address returned in bytes.
Code Example
int getsockname | ( | int | sock, |
SOCKADDR * | name, | ||
int * | namelen | ||
) |
Retrieve local IP address and port number. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[out] | name | structure that will receive IP address and port number. |
[out] | namelen | length of SOCKADDR structure. |
The function getsockname retrieves the local address for a socket.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument name is a pointer to the SOCKADDR structure. If name is not NULL, the local IP address and port number is filled in.
The argument namelen is a pointer to the address length. It should initially contain the amount of space pointed to by name. On return it contains the actual length of the address returned in bytes.
Code Example
int ioctlsocket | ( | int | sock, |
long | cmd, | ||
unsigned long * | argp | ||
) |
Control IO mode of a socket. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[in] | cmd | command to perform:
|
[in] | argp | command's parameter. |
The function ioctlsocket controls the I/O mode of a socket. It can be used on any socket in any state to set or retrieve some operating parameters of the socket.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument cmd specifies a command to perform on a socket. The following commands are supported:
Command | Description |
---|---|
FIONBIO | Sets the blocking or non-blocking socket I/O mode |
FIO_DELAY_ACK | Sets the delay-ack or normal mode for the stream socket |
FIO_KEEP_ALIVE | Sets the keep-alive or timeout mode for the stream socket |
FIO_FLOW_CTRL | Sets the receive flow-control or normal mode for the stream socket |
The argument argp specifies a pointer to the command's parameter.
For the command FIONBIO the argument values are:
*argp value | I/O mode |
---|---|
0 | Blocking mode |
nonzero | Non-blocking mode |
For the command FIO_DELAY_ACK the argument values are:
*argp value | Socket mode | Description |
---|---|---|
0 | Normal mode | Waits for an ACK after each sending packet |
nonzero | Delay-ack mode | Eliminates the delayed acknowledge impact and improves the performance for applications sending large amount of data |
For the command FIO_KEEP_ALIVE the argument values are:
*argp value | Socket mode | Description |
---|---|---|
0 | Timeout mode | After a timeout a stream socket is disconnected |
nonzero | Keep-alive mode | Stream socket sends keep alive segments on timeout to keep a connection alive |
For the command FIO_FLOW_CTRL the argument values are:
*argp value | Socket mode | Description |
---|---|---|
0 | Normal mode | Stream socket dumps excess data, if the receiving buffer is full |
nonzero | Flow-control mode | Stream socket controls the window size and stops the transmitter, if the receiving buffer is full |
Code Example
int listen | ( | int | sock, |
int | backlog | ||
) |
Set a socket in a listening mode. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[in] | backlog | number of connection requests that can be queued. |
The function listen sets the specified socket to listening mode. Before calling the listen function, the bind function must be called.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument backlog specifies a maximum number of connection requests that can be queued.
Code Example
int recv | ( | int | sock, |
char * | buf, | ||
int | len, | ||
int | flags | ||
) |
Receive data on already connected socket. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[out] | buf | pointer to application data buffer to store the data to. |
[in] | len | size of application data buffer (in bytes). |
[in] | flags | message flags:
|
The function recv receives incoming data that has been queued for the socket. This function can be used with both SOCK_STREAM and SOCK_DGRAM type sockets. It reads as much information as currently available up to the size of the buffer specified.
In blocking mode, which is enabled by default in RTOS environment, this functions waits for received data. In non blocking mode, you must call the recv function again if the error code BSD_ERROR_WOULDBLOCK is returned.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument buf is a pointer to the application data buffer for storing the data to. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of SOCK_DGRAM sockets. For socket types SOCK_STREAM, the data is buffered internally so the application can retrieve all data by multiple calls of recv function.
The argument len specifies the size of the application data buffer. The argument flags specifies the message flags:
Flag | Description |
---|---|
MSG_DONTWAIT | The function returns with error code BSD_ERROR_WOULDBLOCK or number of bytes sent instead of blocking the socket. |
MSG_PEEK | The function peeks at incoming data. The data is copied into the buffer, but is not removed from the input queue. |
Code Example
int recvfrom | ( | int | sock, |
char * | buf, | ||
int | len, | ||
int | flags, | ||
SOCKADDR * | from, | ||
int * | fromlen | ||
) |
Receive data from endpoint node. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[out] | buf | pointer to application data buffer to store the data to. |
[in] | len | size of application data buffer (in bytes). |
[in] | flags | message flags:
|
[out] | from | structure that will receive IP address and port number.
|
[out] | fromlen | length of SOCKADDR structure. |
The function recvfrom is used to receive data that has been queued for a socket. It is normally used to receive messages on SOCK_DGRAM socket type, but can also be used to receive a reliable, ordered stream of data on a connected SOCK_STREAM socket type. It reads as much information as currently available up to the size of the buffer specified.
In blocking mode, which is enabled by default in RTOS environment, this functions waits for received data. In non blocking mode, you must call the recvfrom function again if the error code BSD_ERROR_WOULDBLOCK is returned.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument buf is a pointer to the application data buffer for storing the data to. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of SOCK_DGRAM sockets. For socket types SOCK_STREAM, the data is buffered internally so the application can retrieve all data by multiple calls of recvfrom function.
The argument len specifies the size of the application data buffer.
The argument flags specifies the message flags:
Flag | Description |
---|---|
MSG_DONTWAIT | The function returns with error code BSD_ERROR_WOULDBLOCK or number of bytes sent instead of blocking the socket. |
MSG_PEEK | The function peeks at incoming data. The data is copied into the buffer, but is not removed from the input queue. |
The argument from is a pointer to the SOCKADDR structure. If from is not NULL, the source IP address and port number of the datagram is filled in.
The argument fromlen is a pointer to the address length. It should initially contain the amount of space pointed to by from. On return it contains the actual length of the address returned in bytes.
Code Example
int send | ( | int | sock, |
const char * | buf, | ||
int | len, | ||
int | flags | ||
) |
Send data on already connected socket. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[in] | buf | pointer to application data buffer to transmit. |
[in] | len | length of data (in bytes). |
[in] | flags | message flags:
|
The function send is used to send data on an already connected socket. This function is normally used to send a reliable, ordered stream of data bytes on a SOCK_STREAM socket type. It can also be used to send datagrams on a SOCK_DGRAM socket types.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument buf is a pointer to the application data buffer containing data to transmit. The buffer data length is not limited in size. If the data length is too large for one packet, the send function will fragment the data and send it in several successive data packets:
The argument len specifies the length of data in bytes. The argument flags specifies the message flags:
Flag | Description |
---|---|
MSG_DONTWAIT | The function returns with error code BSD_ERROR_WOULDBLOCK or number of bytes sent instead of blocking the socket |
Code Example
int sendto | ( | int | sock, |
const char * | buf, | ||
int | len, | ||
int | flags, | ||
const SOCKADDR * | to, | ||
int | tolen | ||
) |
Send data to endpoint node. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[in] | buf | pointer to application data buffer to transmit. |
[in] | len | length of data (in bytes). |
[in] | flags | message flags:
|
[in] | to | structure containing remote IP address and port. |
[in] | tolen | length of SOCKADDR structure. |
The function sendto is used to send data on a SOCK_DGRAM socket type.
The argument sock specifies a socket descriptor returned from a previous call to socket.
The argument buf is a pointer to the application data buffer containing data to transmit. The buffer data length is not limited in size. If the data length is too large for one packet, the sendto function will fragment the data and send it in several successive data packets:
The argument len specifies the length of data in bytes. The argument flags specifies the message flags:
Flag | Description |
---|---|
MSG_DONTWAIT | The function returns with error code BSD_ERROR_WOULDBLOCK or number of bytes sent instead of blocking the socket |
The argument to is a pointer to the SOCKADDR structure that contains the end point node IP address and port number. The argument tolen specifies the length of SOCKADDR structure.
Code Example
int setsockopt | ( | int | sock, |
int | level, | ||
int | optname, | ||
const char * | optval, | ||
int | optlen | ||
) |
Manipulate options for the socket. [thread-safe].
[in] | sock | socket descriptor obtained with socket. |
[in] | level | level at which the option is defined:
|
[in] | optname | socket option for which the value is to be set:
|
[in] | optval | pointer to the buffer containing the option value. |
[in] | optlen | size of the buffer containing the option value. |
The function setsockopt sets options for a socket. Options may exist at multiple protocol levels.
The argument sock specifies a socket desriptor returned from a previous call to socket.
The argument level describes the level at which the option is defined (for example SOL_SOCKET).
The argument optname is the socket option for which the value is to be set. The optname argument must be a socket option defined within the specified level.
The argument optval points to the buffer containing the value of the optname.
The argument optlen tells the exact length of the option.
Code Example
int socket | ( | int | family, |
int | type, | ||
int | protocol | ||
) |
Create a communication endpoint called socket. [thread-safe].
[in] | family | address family:
|
[in] | type | connection type of a socket:
|
[in] | protocol | protocol type:
|
The function socket creates a communication end point called a socket.
The argument family specifies the address family. Currently the only acceptable value is AF_INET.
The argument type specifies the communication semantics. The following are the currently supported types:
Type | Description |
---|---|
SOCK_STREAM | Provides a reliable connection based data stream that is full-duplex |
SOCK_DGRAM | Provides connectionless communication that is unreliable |
The argument protocol specifies the protocol that must be used with socket type:
Protocol | Description |
---|---|
IPPROTO_TCP | Must be used with SOCK_STREAM socket type |
IPPROTO_UDP | Must be used with SOCK_DGRAM socket type |
0 | The system selects a matching protocol for the socket type |
Code Example