User API

BSD Socket functions and communication flow. More...

Functions
int32_t	socket (int32_t family, int32_t type, int32_t protocol)
	Create a communication endpoint called socket. [thread-safe].
int32_t	bind (int32_t sock, const SOCKADDR *addr, int32_t addrlen)
	Assign a local address and port to a socket. [thread-safe].
int32_t	listen (int32_t sock, int32_t backlog)
	Set a socket in a listening mode. [thread-safe].
int32_t	accept (int32_t sock, SOCKADDR *addr, int32_t *addrlen)
	Accept connect request for a listening socket. [thread-safe].
int32_t	connect (int32_t sock, const SOCKADDR *addr, int32_t addrlen)
	Connect a socket to a remote host. [thread-safe].
int32_t	send (int32_t sock, const char *buf, int32_t len, int32_t flags)
	Send data on already connected socket. [thread-safe].
int32_t	sendto (int32_t sock, const char *buf, int32_t len, int32_t flags, const SOCKADDR *to, int32_t tolen)
	Send data to endpoint node. [thread-safe].
int32_t	sendmsg (int32_t sock, const MSGHDR *msg, int32_t flags)
	Send a message to endpoint node. [thread-safe].
int32_t	recv (int32_t sock, char *buf, int32_t len, int32_t flags)
	Receive data on already connected socket. [thread-safe].
int32_t	recvfrom (int32_t sock, char *buf, int32_t len, int32_t flags, SOCKADDR *from, int32_t *fromlen)
	Receive data from endpoint node. [thread-safe].
int32_t	recvmsg (int32_t sock, MSGHDR *msg, int32_t flags)
	Receive a message from a socket. [thread-safe].
int32_t	closesocket (int32_t sock)
	Close socket and release socket descriptor. [thread-safe].
int32_t	getpeername (int32_t sock, SOCKADDR *name, int32_t *namelen)
	Retrieve IP address and port number of the endpoint node. [thread-safe].
int32_t	getsockname (int32_t sock, SOCKADDR *name, int32_t *namelen)
	Retrieve local IP address and port number. [thread-safe].
int32_t	ioctlsocket (int32_t sock, long cmd, unsigned long *argp)
	Control IO mode of a socket. [thread-safe].
int32_t	setsockopt (int32_t sock, int32_t level, int32_t optname, const char *optval, int32_t optlen)
	Manipulate options for the socket. [thread-safe].
int32_t	getsockopt (int32_t sock, int32_t level, int32_t optname, char *optval, int32_t *optlen)
	Retrieve options for the socket. [thread-safe].
int32_t	select (int32_t nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout)
	Check the status of one or more sockets. [thread-safe].
HOSTENT *	gethostbyname (const char *name, int32_t *err)
	Retrieve host IP address from host name. [thread-safe].
IN_ADDR	inet_addr (const char *cp)
	Convert from text address to a network address. [thread-safe].
int32_t	inet_aton (const char *cp, IN_ADDR *addr)
	Convert from text address to a network address. [thread-safe].
const char *	inet_ntoa (IN_ADDR in)
	Convert from network address to a text string. [not_thread-safe].
int32_t	inet_pton (int32_t af, const char *src, void *dst)
	Convert from text address to a binary network address. [thread-safe].
const char *	inet_ntop (int32_t af, const void *src, char *dst, int32_t size)
	Convert from binary network address to a text string. [thread-safe].

Description

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.
getsockopt	Retrieves options for the socket.
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.
recvmsg	Receives a message from a socket.
select	Tests sockets if ready for reading, writing or have an error pending.
send	Sends outgoing data on a socket.
sendto	Sends outgoing data on a datagram socket to destination address.
sendmsg	Sends a message to destination address.
setsockopt	Manipulate options for the socket.
socket	Creates a communication socket.
inet_addr	Converts address from text address to a network address.
inet_aton	Converts address from text address to a network address.
inet_ntoa	Converts address from network address to a text string.
inet_pton	Converts address from text address to a binary network address.
inet_ntop	Converts address from binary network address to a text string.

Note

• The BSD sockets implementation in the Network Component is not a complete implementation of the BSD API.
• The BSD functions are thread safe and must be used with a CMSIS-RTOS.

Communication Flow

The image below explains the basic communication flow using BSD sockets with TCP.

Flow Diagram for BSD Sockets Communication using TCP

BSD Server

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

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, sd, res;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, SOCK_STREAM, 0);
 
    // Bind to IPv4 any address
    addr.sin_family      = AF_INET;
    addr.sin_port        = htons(1000);
    addr.sin_addr.s_addr = INADDR_ANY;
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
 
    listen (sock, 1);
    sd = accept (sock, NULL, NULL);
    closesocket (sock);
 
    while (1) {
      res = recv (sd, dbuf, sizeof (dbuf), 0);
      if (res <= 0) {
        break;
      }
      if (dbuf[0] == BLINKLED) {
        LED_SetOut (dbuf[1]);
      }
    }
    closesocket (sd);
    osDelay (100);
  }
}

BSD Server Dual-Stack

Dual-Stack sockets offer the ability to create a single IPv6 socket which can handle both IPv6 and IPv4 communication. For example, a TCP listening socket for IPv6 is created, put into dual-stack mode, and bound to port 1000. The dual-stack socket can accept connections from IPv6 TCP clients and IPv4 TCP clients that connect to port 1000.

The IPv4 address is encoded in the IPv4-mapped IPv6 address with the address prefix 0:0:0:0:0:FFFF, last four bytes of the address are the IPv4 address. The IPv4 address in this format can be used in a dual-stack socket communication. If the IPv4 address is converted to a string address with the function inet_ntop, the result is represented in a hybrid dotted decimal notation. For example, the address 192.168.0.100 is converted to a string:

::FFFF:192.168.0.100

Code Example

void Server_Thread (void *arg) {
  SOCKADDR_IN6 addr;
  int32_t sock, sd, res, on;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET6, SOCK_STREAM, 0);
 
    // Disable IPv6-only
    on = 0;
    setsockopt (sock, IPPROTO_IPV6, IPV6_V6ONLY, (char *)&on, sizeof(on));
    
    // Bind to IPv6 any address
    addr.sin6_family   = AF_INET6;
    addr.sin6_port     = htons(1000);
    addr.sin6_addr     = in6addr_any;
    addr.sin6_flowinfo = 0;
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
 
    listen (sock, 1);
    sd = accept (sock, NULL, NULL);
    closesocket (sock);
 
    while (1) {
      res = recv (sd, dbuf, sizeof (dbuf), 0);
      if (res <= 0) {
        break;
      }
      if (dbuf[0] == BLINKLED) {
        LED_SetOut (dbuf[1]);
      }
    }
    closesocket (sd);
    osDelay (100);
  }
}

BSD Client

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

void Client_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, res;
  char dbuf[4];
  uint8_t leds;
 
  while (1) {
    sock = socket (AF_INET, SOCK_STREAM, 0);
 
    addr.sin_family = AF_INET;
    addr.sin_port   = htons(1000);
    addr.sin_addr   = inet_addr ("192.168.0.100");
 
    connect (sock, (SOCKADDR *)&addr, sizeof (addr));
 
    leds = 0x01;
    while (1) {
      // Shift the LEDs
      LED_SetOut (leds);
      if (leds == 0x80) leds = 0x01;
      else              leds <<= 1;
    
      // Send the data to LED Server.
      dbuf[0] = BLINKLED;
      dbuf[1] = p2val;
      res = send (sock, (char *)&dbuf, 2, 0);
      if (res < 0) {
        break;
      }
      osDelay (300);
    }
    closesocket (sock);
  }
}

Function Documentation

accept()

int32_t accept	(	int32_t	sock,
		SOCKADDR *	addr,
		int32_t *	addrlen
	)

Accept connect request for a listening socket. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[out]	addr	structure that will receive IP address and port number. NULL for none.
[in,out]	addrlen	length of SOCKADDR structure.

Returns

status information:

• New socket descriptor (>0).
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Socket not in listen mode.
• BSD_ENOTSUP = Operation not supported for this socket type.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ECONNRESET = Connection reset by the peer.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_ERROR = Unspecified error.

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, this function waits for a connection request. In non blocking mode, you must call the accept function again if the error code BSD_EWOULDBLOCK 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.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example (see socket)

bind()

int32_t bind	(	int32_t	sock,
		const SOCKADDR *	addr,
		int32_t	addrlen
	)

Assign a local address and port to a socket. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	addr	structure containing local IP address and port.
[in]	addrlen	length of SOCKADDR structure.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter or already bound.
• BSD_EADDRINUSE = Address or port already in use.
• BSD_EISCONN = Socket already connected.

The function bind assigns a name to an unnamed socket. The name represents the local address and port of the communication endpoint.

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. If the port is specified as 0, the Network Core assigns a unique port from the dynamic client port range (ephemeral ports).

The argument addrlen specifies the length of the SOCKADDR structure.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.
• You can retrieve the assigned dynamic port with getsockname function.

Code Example (see socket)

closesocket()

int32_t closesocket

(

int32_t

sock

)

Close socket and release socket descriptor. [thread-safe].

Parameters

[in]

sock

socket descriptor obtained with socket.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ERROR = Unspecified error.

The function closesocket closes an existing socket and releases the socket descriptor. Further references to sock fail with BSD_EINVAL error code.

The argument sock specifies a socket descriptor returned from a previous call to socket.

In blocking mode, which is enabled by default, this function will wait until a socket is closed. In non blocking mode, you must call the closesocket function again if the error code BSD_EWOULDBLOCK is returned.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example (see socket)

connect()

int32_t connect	(	int32_t	sock,
		const SOCKADDR *	addr,
		int32_t	addrlen
	)

Connect a socket to a remote host. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	addr	structure containing remote IP address and port.
[in]	addrlen	length of SOCKADDR structure.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter or socket in wrong state.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_EALREADY = Connection already in progress.
• BSD_EINPROGRESS = Operation in progress.
• BSD_EISCONN = Socket is connected.
• BSD_ECONNREFUSED = Connection rejected by the peer.
• BSD_ETIMEDOUT = Operation timed out.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_ERROR = Unspecified error.

The function connect assigns the address of the peer communication endpoint. The function behaves differently according to the type of socket:

• SOCK_STREAM: A connection is established between the endpoints.

  In blocking mode, which is enabled by default, this function waits for a connection to be established.

  In non blocking mode, the function returns the error code BSD_EINPROGRESS and the connection is established asynchronously. Subsequent calls to connect for the same socket, before the connection is established, return the error code BSD_EALREADY. When the connection is established, the call to connect returns the error code BSD_EISCONN.

• SOCK_DGRAM: An address filter is established between the endpoints.

  The address filter is changed with another connect function call. If the socket is not yet bound, the system implicitly binds to a random dynamic port.

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 endpoint node IP address and port number.

The argument addrlen specifies the length of SOCKADDR structure.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example

void Client_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, res, lshift;
  int32_t type = (int32_t)arg;
  char dbuf[4];
  uint8_t p2val;
 
  while (1) {
    sock = socket (AF_INET, type, 0);
 
    addr.sin_port      = htons(PORT_NUM);
    addr.sin_family    = AF_INET;
    addr.sin_addr.s_b1 = IP1;
    addr.sin_addr.s_b2 = IP2;
    addr.sin_addr.s_b3 = IP3;
    addr.sin_addr.s_b4 = IP4;
 
    connect (sock, (SOCKADDR *)&addr, sizeof (addr));
 
    lshift = 1;
    p2val  = 0x01;
    while (1) {
      // Shift the LEDs 
      LED_SetOut (p2val);
      p2val = lshift ? (p2val << 1) : (p2val >> 1);
      if (p2val == 0x80) lshift = 0;
      if (p2val == 0x01) lshift = 1;
    
      // Send the data to LED Server.
      dbuf[0] = BLINKLED;
      dbuf[1] = p2val;
      res = send (sock, (char *)&dbuf, 2, 0);
      if (res < 0) {
        break;
      }
      osDelay (100 * SPEED);
    }
    closesocket (sock);
  }
}

gethostbyname()

HOSTENT * gethostbyname	(	const char *	name,
		int32_t *	err
	)

Retrieve host IP address from host name. [thread-safe].

Parameters

[in]	name	host name.
[out]	err	pointer to where to return error code (NULL for none): 0 = Operation successful. BSD_EINVAL = Invalid parameter. BSD_ELOCKED = Resolver locked by another thread. BSD_ETIMEDOUT = Operation timed out. BSD_EHOSTNOTFOUND = Host not found. BSD_ERROR = Unspecified error.

Returns

status information:

• HOSTENT result structure.
• NULL in case of error.

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.

Note

• To use this function, you must enable the DNS client in the selection of RTE Components.
• If a negative number is returned, it represents an error code.

Code Example

static const char *hosts[] = {
  "www.google.com",
  "www.keil.com",
  "www.microsoft.com",
  "www.yahoo.com",
  NULL
};
 
void Resolver_Thread (void *arg) {
  HOSTENT *host;
  IN_ADDR *addr;
  int32_t i, j, err;
 
  for (i = 0; ; i++) {
    if (hosts[i] == NULL) i = 0;
    printf ("Host: %s\n",hosts[i]);
 
    host = gethostbyname (hosts[i], &err);
    if (host == NULL) {
      if (err == BSD_EHOSTNOTFOUND) {
        printf ("Hostname does not exist\n");
      }
    }
    else if (host->h_addrtype == AF_INET) {
      for (j = 0; host->h_addr_list[j]; j++) {
        addr = (IN_ADDR *)host->h_addr_list[j];
        printf("IP Address: %s\n", inet_ntoa(addr->sin_addr));
      }
    }
    osDelay (300);
  }
}

getpeername()

int32_t getpeername	(	int32_t	sock,
		SOCKADDR *	name,
		int32_t *	namelen
	)

Retrieve IP address and port number of the endpoint node. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[out]	name	structure that will receive IP address and port number.
[in,out]	namelen	length of SOCKADDR structure.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ENOTCONN = Socket not connected.

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

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, sd, res, addrlen;
  int32_t type = (int32_t)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);
 
    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = AF_INET;
    addr.sin_addr.s_addr = INADDR_ANY;
 
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
 
    if (type == SOCK_STREAM) {
      listen (sock, 1);
      sd = accept (sock, NULL, NULL);
      closesocket (sock);
      sock = sd;
    }
 
    while (1) {
      res = recv (sock, dbuf, sizeof (dbuf), 0);
      if (res <= 0) {
        break;
      }
      procrec ((uint8_t *)dbuf);
      addrlen = sizeof (addr);
      getpeername (sock, (SOCKADDR *)&addr, &addrlen);
      printf ("Remote IP:   %s\n", inet_ntoa(addr.sin_addr));
      printf ("Remote port: %d\n", ntohs (addr.sin_port));
    }
    closesocket (sock);
  }
}

getsockname()

int32_t getsockname	(	int32_t	sock,
		SOCKADDR *	name,
		int32_t *	namelen
	)

Retrieve local IP address and port number. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[out]	name	structure that will receive IP address and port number.
[in,out]	namelen	length of SOCKADDR structure.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter or socket not bound.

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

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, res, addrlen;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, SOCK_DGRAM, IPPROTO_UDP);
 
    addr.sin_port        = htons(1001);
    addr.sin_family      = AF_INET;
    addr.sin_addr.s_addr = INADDR_ANY;
 
    bind (sock, (SOCKADDR *)&addr, sizeof (addr));
 
    addrlen = sizeof (addr);
    getsockname (sock, (SOCKADDR *)&addr, &addrlen);
    printf ("Local IP:   %s\n", inet_ntoa(addr.sin_addr));
    printf ("Local port: %d\n", ntohs (addr.sin_port));
 
    while (1) {
      res = recv (sock, dbuf, sizeof (dbuf), 0);
      if (res <= 0) {
        break;
      }
      procrec ((uint8_t *)dbuf);
    }
    closesocket (sock);
  }
}

getsockopt()

int32_t getsockopt	(	int32_t	sock,
		int32_t	level,
		int32_t	optname,
		char *	optval,
		int32_t *	optlen
	)

Retrieve options for the socket. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	level	level at which the option is defined: SOL_SOCKET = Socket level. IPPROTO_IP = IPv4 protocol level. IPPROTO_IPV6 = IPv6 protocol level.
[in]	optname	socket option for which the value is to be retrieved: SO_TYPE = Type of a socket. SO_KEEPALIVE = Keep Alive. SO_RCVTIMEO = Timeout for blocking receive (in ms). SO_SNDTIMEO = Timeout for blocking send (in ms). SO_BINDTODEVICE = Bound network interface (class and number). IP_RECVDSTADDR = Receive Destination IP Address. IP_TOS = Type of Service (TOS). IP_TTL = Time to Live (TTL). IPV6_TCLASS = Traffic Class. IPV6_MULTICAST_HOPS = Multi-cast Hop Limit. IPV6_RECVDSTADDR = Receive Destination IPv6 Address. IPV6_V6ONLY = Restrict to IPv6 communications only.
[out]	optval	pointer to the buffer that will receive the option value.
[in,out]	optlen	input length of buffer, return length of the data.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ENOTSUP = Option not supported for this socket type.

The function getsockopt retrieves options for a socket. Options may exist at multiple protocol levels.

The argument sock specifies a socket descriptor 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 retrieved and must be defined within the specified level.

The argument optval points to the buffer that will receive the value of the optname.

The argument optlen contains the length of the buffer at the input and returns the length of the option information on the output.

Code Example

// Retrieve keep-alive mode for stream socket
char optval;
int32_t optlen = sizeof(optval);
 
getsockopt (sock, SOL_SOCKET, SO_KEEPALIVE, &optval, &optlen);
 
if (optval != 0) {
  printf ("Keep-alive mode is active.");
}

inet_addr()

IN_ADDR inet_addr

(

const char *

cp

)

Convert from text address to a network address. [thread-safe].

Parameters

[in]

cp

text address in standard dotted-decimal notation.

Returns

status information:

• Internet address on success.
• INADDR_NONE = on error.

The function inet_addr converts the specified string to an integer value suitable for use as an Internet address.

The argument cp is a pointer to the null-terminated string in the standard IPv4 dotted decimal notation.

The function returns the converted Internet address on success, or INADDR_NONE if failed.

Code Example (see inet_aton)

inet_aton()

int32_t inet_aton	(	const char *	cp,
		IN_ADDR *	addr
	)

Convert from text address to a network address. [thread-safe].

Parameters

[in]	cp	text address in standard dotted-decimal notation.
[out]	addr	buffer where the converted IPv4 address is to be stored.

Returns

status information:

• 1 = Conversion successful.
• 0 = Conversion failed.

The function inet_aton converts the specified string to a network address, and stores the address in the structure provided.

The argument cp is a pointer to the null-terminated string in the standard IPv4 dotted decimal notation.

The argument addr is a pointer to the buffer, where the converted address is to be stored.

The function returns 1 if the address is successfully converted, or 0 if the conversion failed.

Code Example

struct sockaddr_in sa;
const char *some_addr;
 
inet_aton("10.0.0.1", &sa.sin_addr); // store IP in sa
 
some_addr = inet_ntoa(sa.sin_addr);  // return the IP
printf("%s\n", some_addr);           // prints "10.0.0.1"
 
// This call is the same as the inet_aton() call, above:
sa.sin_addr = inet_addr("10.0.0.1");

inet_ntoa()

const char * inet_ntoa

(

IN_ADDR

in

)

Convert from network address to a text string. [not_thread-safe].

Parameters

[in]

in

Internet IPv4 host address to convert.

Returns

pointer to the formatted string.

The function inet_ntoa converts the specified Internet host address to a string in the standard dotted decimal notation.

The argument in is the Internet host address to be converted.

The function returns a pointer to the null-terminated string in the standard IPv4 dotted decimal notation.

Note

The function uses a static buffer for the converted address and is therefore not thread safe.

Code Example (see inet_aton)

inet_ntop()

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

Convert from binary network address to a text string. [thread-safe].

Parameters

[in]	af	address family: AF_INET = Internet Address Family (IPv4). AF_INET6 = Internet Address Family version 6 (IPv6).
[in]	src	binary address in network byte order to be converted.
[out]	dst	buffer where the converted text address is to be stored.
[in]	size	size of the buffer, at least: INET_ADDRSTRLEN for AF_INET. INET6_ADDRSTRLEN for AF_INET6.

Returns

pointer to the formatted string.

• NULL in case of error.

The function inet_ntop converts an address from network format in network byte order to presentation format.

The argument af specifies the address family. Currently, only AF_INET and AF_INET6 are supported.

The argument src is a pointer to the network address. The format of the address is interpreted according to argument af.

The argument dst is a pointer to the buffer where the converted address is to be stored.

The argument size specifies the size of the buffer pointed to by dst. The size must be at least INET_ADDRSTRLEN bytes for an IPv4 address and INET6_ADDRSTRLEN bytes for an IPv6 address.

The function returns a pointer to dst if the address is successfully converted, or NULL if the conversion failed.

Code Example (see inet_pton)

inet_pton()

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

Convert from text address to a binary network address. [thread-safe].

Parameters

[in]	af	address family: AF_INET = Internet Address Family (IPv4). AF_INET6 = Internet Address Family version 6 (IPv6).
[in]	src	text address to be converted.
[out]	dst	buffer where the converted address is to be stored.

Returns

status information:

• 1 = Conversion successful.
• 0 = Conversion failed.

The function inet_pton converts an address from presentation format to network format in network byte order.

The argument af specifies the address family. Currently, only AF_INET and AF_INET6 are supported.

The argument src is a pointer to the null-terminated presentation format address. The format of the address is interpreted according to argument af.

The argument dst is a pointer to the buffer where the converted address is to be stored.

The function returns 1 if the address is successfully converted, or 0 if the conversion failed.

Code Example

struct sockaddr_in sa;
char str[INET_ADDRSTRLEN];
 
// Store this IP address in sa
inet_pton(AF_INET, "192.168.0.100", &(sa.sin_addr));
 
// Now get it back and print it
inet_ntop(AF_INET, &(sa.sin_addr), str, INET_ADDRSTRLEN);
 
printf("%s\n", str);     // prints "192.168.0.100"

ioctlsocket()

int32_t ioctlsocket	(	int32_t	sock,
		long	cmd,
		unsigned long *	argp
	)

Control IO mode of a socket. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	cmd	command to perform: FIONBIO = enable non-blocking mode.
[in]	argp	command's parameter.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ENOTSUP = Option not supported for this socket type.

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

Note

• You must call the socket function before any other function calls to the BSD socket.
• Negative return numbers represent error codes.
• The blocking mode is enabled by default.

Code Example

void Server_Thread (void *arg) {
  int32_t sock, res;
  long sck_mode;
 
  sock = socket (AF_INET, SOCK_STREAM, IPPROTO_TCP);
 
  // 0= blocking, 1= non-blocking 
  sck_mode = 1;
  res = ioctlsocket (sock, FIONBIO, &sck_mode);
  if (res == 0) {
    printf ("Nonblocking mode enabled.\n");
  }
  else {
    printf ("ioctlsocket() error\n!");
  }
  ..
}

listen()

int32_t listen	(	int32_t	sock,
		int32_t	backlog
	)

Set a socket in a listening mode. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	backlog	number of connection requests that can be accepted.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter, socket not bound or already listening.
• BSD_ENOTSUP = Operation not supported for this socket type.
• BSD_ERROR = Failed to create socket backlog.

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

This is different from the standard BSD listening function. The reason for this is that BSD sockets in the network component are just a layer on top of native TCP Socket. TCP sockets, however, are static, meaning that they are defined at compile time and are not dynamically allocated objects.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example (see socket)

recv()

int32_t recv	(	int32_t	sock,
		char *	buf,
		int32_t	len,
		int32_t	flags
	)

Receive data on already connected socket. [thread-safe].

Parameters

[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: MSG_DONTWAIT = don't wait for data. MSG_PEEK = peek at incoming data. 0 = for none.

Returns

status information:

• Number of bytes received (>0).
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_ENOTCONN = Socket not connected.
• BSD_ECONNRESET = Connection reset by the peer.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ETIMEDOUT = Operation timed out.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_ERROR = Unspecified error.

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. The excess data is treated differently according to the type of socket:

• SOCK_STREAM: The excess data is buffered internally.

  The application can retrieve all data by multiple calls of recv function.

• SOCK_DGRAM: The excess message data is silently discarded.

  The data is extracted from the first enqueued datagram. If the datagram or message is larger than the buffer specified, the buffer is filled with the first part of the datagram, the excess data of this datagram is silently discarded. All subsequent messages that are enqueued, are retained. The message size is currently limited to 2000 characters. You need to enable IP Fragmentation in the interface configuration so that you can receive 2000 byte datagram messages.

In blocking mode, which is enabled by default, this function waits for received data. In non blocking mode, you must call the recv function again if the error code BSD_EWOULDBLOCK 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.

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_EWOULDBLOCK or number of bytes received 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.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example (see socket)

recvfrom()

int32_t recvfrom	(	int32_t	sock,
		char *	buf,
		int32_t	len,
		int32_t	flags,
		SOCKADDR *	from,
		int32_t *	fromlen
	)

Receive data from endpoint node. [thread-safe].

Parameters

[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: MSG_DONTWAIT = don't wait for data. MSG_PEEK = peek at incoming data. 0 = for none.
[out]	from	structure that will receive IP address and port number. NULL for none.
[in,out]	fromlen	length of SOCKADDR structure.

Returns

status information:

• Number of bytes received (>0).
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_ENOTCONN = Socket not connected.
• BSD_ECONNRESET = Connection reset by the peer.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ETIMEDOUT = Operation timed out.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_ERROR = Unspecified error.

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. The excess data is treated differently according to the type of socket:

• SOCK_STREAM: The excess data is buffered internally.

  The application can retrieve all data by multiple calls of recvfrom function.

• SOCK_DGRAM: The excess message data is silently discarded.

  The data is extracted from the first enqueued datagram. If the datagram or message is larger than the buffer specified, the buffer is filled with the first part of the datagram, the excess data of this datagram is silently discarded. All subsequent messages that are enqueued, are retained. The message size is currently limited to 2000 characters. You need to enable IP Fragmentation in the interface configuration so that you can receive 2000 byte datagram messages.

In blocking mode, which is enabled by default, this function waits for received data. In non blocking mode, you must call the recvfrom function again if the error code BSD_EWOULDBLOCK 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.

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_EWOULDBLOCK or number of bytes received 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 will be 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.

If the socket type is SOCK_STREAM, arguments from and fromlen are ignored.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.
• The number of bytes actually read can be less than len.

Code Example

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, res, addrlen;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, SOCK_DGRAM, 0);
 
    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = AF_INET;
    addr.sin_addr.s_addr = INADDR_ANY;
 
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
 
    while (1) {
      addrlen = sizeof (addr);
      res = recvfrom (sock, dbuf, sizeof (dbuf), 0, (SOCKADDR *)&addr, &addrlen);
      if (res <= 0) {
        break;
      }
      procrec ((uint8_t *)dbuf);
      printf ("Remote IP:   %s\n", inet_ntoa(addr.sin_addr));
      printf ("Remote port: %d\n", ntohs (addr.sin_port));
    }
    closesocket (sock);
  }
}

recvmsg()

int32_t recvmsg	(	int32_t	sock,
		MSGHDR *	msg,
		int32_t	flags
	)

Receive a message from a socket. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in,out]	msg	pointer to MSGHDR structure containing: pointer to buffer to store the source address to (NULL for none). array of application buffer(s) for the incomming message. pointer to buffer for the ancillary data (NULL for none).
[in]	flags	message flags: MSG_DONTWAIT = don't wait for data. MSG_PEEK = peek at incoming data. 0 = for none.

Returns

status information:

• Number of bytes received (>0).
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_ENOTSUP = Operation not supported.
• BSD_ENOTCONN = Socket not connected.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ETIMEDOUT = Operation timed out.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_ERROR = Unspecified error.

The function recvmsg is used to receive a message from a SOCK_STREAM or SOCK_DGRAM socket. It is normally used with SOCK_DGRAM sockets because it permits the application to retrieve the source address of received data.

In blocking mode, which is enabled by default, this function waits for received data. In non blocking mode, you must call the recvmsg function again if the error code BSD_EWOULDBLOCK is returned.

The argument sock specifies a socket descriptor returned from a previous call to socket.

The argument msg is a pointer to the msghdr structure, containing both the buffer to store the source address and the buffers for the incoming message.

• The msg_name member is a pointer to the SOCKADDR structure. If msg_name is not NULL, the source IP address and port number of the datagram will be filled in.
• The msg_namelen member is the address length. It should initially contain the amount of space pointed to by msg_name. On return it contains the actual length of the address returned in bytes.
• The msg_iov member is a pointer to scatter/gatther array of type IOVEC. This array can specify one or more buffers, where the received data shall be stored.
• The msg_iovlen member contains the number of IOVEC buffers, that are available in the IOVEC array.
• The msg_control member is a pointer to a buffer, that will receive ancillary data.
• The msg_controllen member is the buffer length. It should initially contain the amount of space pointed to by msg_control. On return it contains the actual length of the control data returned in bytes. The control data can be processed with the following macros:

Macro name	Description
CMSG_FIRSTHDR(mhdr)	Returns a pointer to the first CMSGHDR structure in the mhdr.
CMSG_NXTHDR(mhdr,cmsg)	Returns a pointer to the CMSGHDR structure describing the next ancillary data object.
CMSG_DATA(cmsg)	Returns a pointer to the data of ancillary data object.
CMSG_ALIGN(len)	Rounds the argument up to the next even multiple of 4 bytes.
CMSG_LEN(len)	Gives the length of an ancillary data object without padding.
CMSG_SPACE(len)	Gives the length of an ancillary data object including the padding needed.

• The msg_flags member is ignored on input, but may contain meaningful values on output:

Flag	Description
MSG_TRUNC	Normal data was truncated, excess bytes are discarded in case of SOCK_DGRAM sockets.
MSG_CTRUNC	Control data was truncated, ancillary data buffer is too small.

The argument flags specifies the message flags:

Flag	Description
MSG_DONTWAIT	The function returns with error code BSD_EWOULDBLOCK or number of bytes received 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.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  IN_ADDR     dst_ip;
  MSGHDR  msg;
  IOVEC   iov;
  union {
    CMSGHDR  cm;
    uint8_t  raw[32];
  } control_un;
  CMSGHDR *cmsg;
  int32_t sock, res;
  char dbuf[4];
  char enable;
 
  while (1) {
    sock = socket (AF_INET, SOCK_DGRAM, 0);
 
    addr.sin_family      = AF_INET;
    addr.sin_port        = htons(PORT_NUM);
    addr.sin_addr.s_addr = INADDR_ANY;
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
 
    // Enable receiving destination IPv4 address
    enable = 1;
    setsockopt (sock, IPPROTO_IP, IP_RECVDSTADDR, &enable, sizeof(enable));
 
    // Specify receive IO buffer
    iov.iov_base    = &dbuf[0];
    iov.iov_len     = sizeof(dbuf);
 
    // Construct message header
    msg.msg_iov         = &iov;
    msg.msg_iovlen      = 1;
    msg.msg_name        = &addr;
    msg.msg_namelen     = sizeof(addr);
    msg.msg_control     = &control_un.cm;
    msg.msg_controllen  = sizeof(control_un);
 
    while (1) {
      res = recvmsg (sock, &msg, 0);
      if (res <= 0) {
        break;
      }
 
      // Process control data
      for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
        if (cmsg->cmsg_level == IPPROTO_IP && cmsg->cmsg_type == IP_RECVDSTADDR) {
          IN_ADDR *pia = (IN_ADDR *)CMSG_DATA(cmsg);
          dst_ip.sin_addr.s_addr = pia->s_addr;
        }
      }
 
      // Process normal data
      procrec ((uint8_t *)dbuf);
      printf ("Remote IP:   %s\n", inet_ntoa(addr.sin_addr));
      printf ("Remote port: %d\n", ntohs (addr.sin_port));
    }
    closesocket (sock);
  }
}

select()

int32_t select	(	int32_t	nfds,
		fd_set *	readfds,
		fd_set *	writefds,
		fd_set *	errorfds,
		struct timeval *	timeout
	)

Check the status of one or more sockets. [thread-safe].

Parameters

[in]	nfds	range of sockets to be checked.
[in,out]	readfds	pointer to the set of sockets to check for read. NULL for none.
[in,out]	writefds	pointer to the set of sockets to check for write. NULL for none.
[in,out]	errorfds	pointer to the set of sockets to check for error. NULL for none.
[in]	timeout	pointer to maximum time for select to wait. NULL for blocking wait for event.

Returns

status information:

• number of ready sockets (>0)
• 0 = Operation timed out.
• BSD_EINVAL = Invalid parameter.
• BSD_ERROR = Suspend operation failed.

The function select indicates which of the specified sockets is ready for reading, ready for writing, or has an error condition pending. If the specified condition is false for all of the specified sockets, select blocks, up to the specified timeout interval, until the specified condition is true for at least one of the specified sockets.

The argument nfds specifies the range of sockets to be tested. The select function tests sockets in the range of 0 to nfds-1.

The argument readfds specifies the set of sockets to be checked for being ready to read on input, and on output indicates which sockets are ready to read. If the value of readfds is NULL, the sockets are not checked for being ready to read.

The argument writefds specifies the set of sockets to be checked for being ready to write on input, and on output indicates which sockets are ready to write. If the value of writefds is NULL, the sockets are not checked for being ready to write.

The argument errorfds specifies the set of sockets to be checked for error conditions pending on input, and on output indicates which sockets have error condition pending. If the value of errorfds is NULL, the sockets are not checked for error condition pending.

On exit, each set of sockets is modified in place to indicate which sockets actually changed status. Thus, if using select within a loop, the sets must be reinitialized before each call.

The argument timeout specifies a maximum interval to wait for the selection to complete. If the value of timeout is NULL, the select function blocks until an event occurs. If both members of the timeout structure are 0, select function does not block.

The set of sockets of type fd_set can be initialized and tested with the following macros:

Macro name	Description
FD_SET(fd, set)	Sets the bit for the socket fd in the set of sockets specified with set.
FD_CLR(fd, set)	Clears the bit for the socket fd in the set of sockets specified with set.
FD_ISSET(fd, set)	Returns a nonzero value if the bit for the socket fd is set in the set of sockets specified with set, and 0 otherwise.
FD_ZERO(set)	Initialises the set of sockets set to have zero bits for all socket descriptors.

Note

• If a negative number is returned, it represents an error code.

Code Example

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, sd, res, addrlen;
  struct fd_set read_fds;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, SOCK_STREAM, 0);
 
    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = AF_INET;
    addr.sin_addr.s_addr = INADDR_ANY;
 
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
 
    listen (sock, 1);
    sd = accept (sock, NULL, NULL);
    closesocket (sock);
    sock = sd;
 
    while (1) {
      FD_ZERO (&read_fds);
      FD_SET (sock, &read_fds);
      res = select (sock+1, &read_fds, NULL, NULL, NULL);
      if (res <= 0) {
        break;
      }
      if (FD_ISSET (sock, &read_fds) {
        // Data is ready, recv will not block
        res = recv (sock, dbuf, sizeof (dbuf), 0);
        if (res <= 0) {
          break;
        }
        procrec ((uint8_t *)dbuf);
      }
    }
    closesocket (sock);
  }
}

send()

int32_t send	(	int32_t	sock,
		const char *	buf,
		int32_t	len,
		int32_t	flags
	)

Send data on already connected socket. [thread-safe].

Parameters

[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: MSG_DONTWAIT = don't wait to send data. 0 = for none.

Returns

status information:

• Number of bytes sent (>0).
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_ENOTCONN = Socket not connected.
• BSD_ECONNRESET = Connection reset by the peer.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ETIMEDOUT = Operation timed out.
• BSD_EDESTADDRREQ = Destination address required.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_EMSGSIZE = Message too large.
• BSD_ENOMEM = Not enough memory.
• BSD_ERROR = Unspecified error.

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:

• In blocking mode, which is enabled by default, this function returns after the data has been successfully queued for transmission.
• In non blocking mode, the function returns immediately without blocking the system.

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_EWOULDBLOCK or number of bytes sent instead of blocking the socket

Return value, when positive, represents the number of bytes sent, which can be less than len.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents locally detected error code.

Code Example (see connect)

sendmsg()

int32_t sendmsg	(	int32_t	sock,
		const MSGHDR *	msg,
		int32_t	flags
	)

Send a message to endpoint node. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	msg	pointer to MSGHDR structure containing: pointer to target address (NULL for none). array of application buffer(s) containing the message. pointer to the ancillary data (NULL for none).
[in]	flags	message flags: 0 = for none.

Returns

status information:

• Number of bytes sent (>0).
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_ENOTSUP = Operation not supported.
• BSD_EDESTADDRREQ = Destination address required.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_EMSGSIZE = Message too large.
• BSD_ENOMEM = Not enough memory.
• BSD_ERROR = Unspecified error.

The function sendmsg is used to send a message from a SOCK_STREAM or SOCK_DGRAM socket. It is normally used with SOCK_DGRAM sockets because it permits the application to specify the destination address where the message is to be sent to.

The argument sock specifies a socket descriptor returned from a previous call to socket.

The argument msg is a pointer to the msghdr structure, containing both the destination address and the buffers for the outgoing message.

• The msg_name member is a pointer to the SOCKADDR structure that contains the IP address and port number of the endpoint node. If msg_name is NULL, the destination address specified with a call to connect function is used.
• The msg_namelen member is the address length in bytes.
• The msg_iov member is a pointer to scatter/gatther array of type IOVEC. This array can specify one or more buffers, containing the data to be sent.
• The msg_iovlen member contains the number of IOVEC buffers, that are available in the IOVEC array.
• The msg_control member is a pointer to a buffer, that contains the ancillary data.
• The msg_controllen member is the ancillary data length.
• The msg_flags member is ignored.

The argument flags specifies the message flags.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example

char msg1[] = { "Message part 1" };
char msg2[] = { "Message part 2" };
char msg3[] = { "Message part 3" };
SOCKADDR_IN addr;
MSGHDR  msg;
IOVEC   iov[3];
  
  sock = socket (AF_INET, SOCK_DGRAM, 0);
 
  // Specify destination address
  addr.sin_family = AF_INET;
  addr.sin_port   = htons(1025);
  addr.sin_addr   = inet_addr("10.0.0.1");
 
  // Specify message buffers
  iov[0].iov_base = &msg1;
  iov[0].iov_len  = strlen(msg1);
  iov[1].iov_base = &msg2;
  iov[1].iov_len  = strlen(msg2);
  iov[2].iov_base = &msg3;
  iov[2].iov_len  = strlen(msg3);
     
  // Construct message header
  msg.msg_iov        = &iov[0];
  msg.msg_iovlen     = 3;
  msg.msg_name       = &addr;
  msg.msg_namelen    = sizeof(addr);
  msg.msg_control    = NULL;
  msg.msg_controllen = 0;
 
  res = sendmsg (sock, &msg, 0);
  if (res <= 0) {
    // Error
  }
  closesocket (sock);

sendto()

int32_t sendto	(	int32_t	sock,
		const char *	buf,
		int32_t	len,
		int32_t	flags,
		const SOCKADDR *	to,
		int32_t	tolen
	)

Send data to endpoint node. [thread-safe].

Parameters

[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: MSG_DONTWAIT = don't wait to send data. 0 = for none.
[in]	to	structure containing remote IP address and port.
[in]	tolen	length of SOCKADDR structure.

Returns

status information:

• Number of bytes sent (>0).
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ELOCKED = Socket locked by another thread.
• BSD_ENOTCONN = Socket not connected.
• BSD_ECONNRESET = Connection reset by the peer.
• BSD_EWOULDBLOCK = Operation would block.
• BSD_ETIMEDOUT = Operation timed out.
• BSD_EDESTADDRREQ = Destination address required.
• BSD_ECONNABORTED = Connection aborted locally.
• BSD_EMSGSIZE = Message too large.
• BSD_ENOMEM = Not enough memory.
• BSD_ERROR = Unspecified error.

The function sendto is used to send data. It is normally used to send messages on a SOCK_DGRAM socket type, but can also be used to send data on a connected SOCK_STREAM socket type.

If the socket type is SOCK_DGRAM and the socket is not yet bound, the system implicitly binds to a random dynamic port.

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:

• In blocking mode, which is enabled by default, this function returns after the data has been successfully queued for transmission.
• In non blocking mode, the function returns immediately without blocking the system.

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_EWOULDBLOCK or number of bytes sent instead of blocking the socket

The argument to is a pointer to the SOCKADDR structure that contains the endpoint node IP address and port number.

The argument tolen specifies the length of SOCKADDR structure.

If the socket type is SOCK_STREAM, arguments to and tolen are ignored.

Return value, when positive, represents the number of bytes sent, which can be less than len.

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents locally detected error code.

Code Example

void Client_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, res, lshift;
  char dbuf[4];
  uint8_t p2val;
 
  while (1) {
    sock = socket (AF_INET, SOCK_DGRAM, 0);
 
    addr.sin_port      = htons(PORT_NUM);
    addr.sin_family    = AF_INET;
    addr.sin_addr.s_b1 = IP1;
    addr.sin_addr.s_b2 = IP2;
    addr.sin_addr.s_b3 = IP3;
    addr.sin_addr.s_b4 = IP4;
 
    lshift = 1;
    p2val  = 0x01;
    while (1) {
      // Shift the LEDs 
      LED_SetOut (p2val);
      p2val = lshift ? (p2val << 1) : (p2val >> 1);
      if (p2val == 0x80) lshift = 0;
      if (p2val == 0x01) lshift = 1;
 
      // Send the data to LED Server.
      dbuf[0] = BLINKLED;
      dbuf[1] = p2val;
      res = sendto (sock, (char *)&dbuf, 2, 0, (SOCKADDR *)&addr, sizeof (addr));
      if (res < 0) {
        break;
      }
      osDelay (100 * SPEED);
    }
    closesocket (sock);
  }
}

setsockopt()

int32_t setsockopt	(	int32_t	sock,
		int32_t	level,
		int32_t	optname,
		const char *	optval,
		int32_t	optlen
	)

Manipulate options for the socket. [thread-safe].

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	level	level at which the option is defined: SOL_SOCKET = Socket level. IPPROTO_IP = IPv4 protocol level. IPPROTO_IPV6 = IPv6 protocol level.
[in]	optname	socket option for which the value is to be set: SO_KEEPALIVE = Keep Alive. SO_RCVTIMEO = Timeout for blocking receive (in ms). SO_SNDTIMEO = Timeout for blocking send (in ms). SO_BINDTODEVICE = Network interface to bind (class and number). IP_TOS = Type of Service (TOS). IP_TTL = Time to Live (TTL). IP_RECVDSTADDR = Receive Destination IP Address. IPV6_TCLASS = Traffic Class. IPV6_MULTICAST_HOPS = Multi-cast Hop Limit. IPV6_RECVDSTADDR = Receive Destination IPv6 Address. IPV6_V6ONLY = Restrict to IPv6 communications only.
[in]	optval	pointer to the buffer containing the option value.
[in]	optlen	size of the buffer containing the option value.

Returns

status information:

• 0 = Operation successful.
• BSD_ESOCK = Invalid socket descriptor or socket not created.
• BSD_EINVAL = Invalid parameter.
• BSD_ENOTSUP = Option not supported for this socket type.
• BSD_ERROR = Option failed, socket already bound.

The function setsockopt sets options for a socket. Options may exist at multiple protocol levels.

The argument sock specifies a socket descriptor 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

// Timeout 5 sec
int32_t timeout = 5000;
 
setsockopt (sock, SOL_SOCKET, SO_RCVTIMEO, (char *)&timeout, sizeof (timeout));

socket()

int32_t socket	(	int32_t	family,
		int32_t	type,
		int32_t	protocol
	)

Create a communication endpoint called socket. [thread-safe].

Parameters

[in]	family	address family: AF_INET = address family IPv4. AF_INET6 = address family IPv6.
[in]	type	connection type of a socket: SOCK_STREAM = connection based type. SOCK_DGRAM = datagram connectionless type.
[in]	protocol	protocol type: IPPROTO_TCP = must be used with SOCK_STREAM type. IPPROTO_UDP = must be used with SOCK_DGRAM TYPE. 0 = for system auto-select.

Returns

status information:

• Socket descriptor (>0).
• BSD_EINVAL = Invalid parameter.
• BSD_ENOMEM = No free sockets available.

The function socket creates a communication endpoint called a socket.

The argument family specifies the address family. Currently, only AF_INET and AF_INET6 address families are supported. By default, the IPv4 socket operates over the IPv4 protocol, the IPv6 socket operates over the IPv6 protocol. To convert an IPv6 socket to a dual-stack socket, the setsockopt function must be called with the IPV6_V6ONLY socket option to set this value to zero before the socket is bound to an IP address. When communicating with a dual-stack socket, the socket can operate via both, IPv4 or IPv6.

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

Note

• You must call the socket function before any other function calls to the BSD socket.
• If a negative number is returned, it represents an error code.

Code Example (Stream Socket)

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, sd, res;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, SOCK_STREAM, 0);
 
    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = AF_INET;
    addr.sin_addr.s_addr = INADDR_ANY;
 
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
    listen (sock, 1);
    sd = accept (sock, NULL, NULL);
    closesocket (sock);
    sock = sd;
 
    while (1) {
      res = recv (sock, dbuf, sizeof (dbuf), 0);
      if (res <= 0) {
        break;
      }
      if (dbuf[0] == BLINKLED) {
        LED_SetOut (dbuf[1]);
      }
    }
    closesocket (sock);
  }
}

Code Example (Datagram Socket)

void Server_Thread (void *arg) {
  SOCKADDR_IN addr;
  int32_t sock, res;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, SOCK_DGRAM, 0);
 
    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = AF_INET;
    addr.sin_addr.s_addr = INADDR_ANY;
 
    bind (sock, (SOCKADDR *)&addr, sizeof(addr));
 
    while (1) {
      res = recv (sock, dbuf, sizeof (dbuf), 0);
      if (res <= 0) {
        break;
      }
      if (dbuf[0] == BLINKLED) {
        LED_SetOut (dbuf[1]);
      }
    }
    closesocket (sock);
  }
}