BSD Socket

BSD socket routines enable BSD compliant communication over TCP/IP. More...

Structures
struct	SOCKADDR
	Generic Socket Address structure. More...
struct	IN_ADDR
	Generic IPv4 Address structure. More...
union	IN_ADDR.__unnamed__
struct	IN_ADDR.__unnamed__.__unnamed__
struct	SOCKADDR_IN
	IPv4 Socket Address structure. More...
struct	HOSTENT
	BSD Host Entry structure. More...

Functions
int	socket (int family, int type, int protocol)
	Create a communication endpoint called socket.
int	bind (int sock, const SOCKADDR *addr, int addrlen)
	Assign a local address and port to a socket.
int	listen (int sock, int backlog)
	Set a socket in a listening mode.
int	accept (int sock, SOCKADDR *addr, int *addrlen)
	Accept connect request for a listening socket.
int	connect (int sock, SOCKADDR *addr, int addrlen)
	Connect a socket to a remote host.
int	send (int sock, const char *buf, int len, int flags)
	Send data on already connected socket.
int	sendto (int sock, const char *buf, int len, int flags, SOCKADDR *to, int tolen)
	Send data to endpoint node.
int	recv (int sock, char *buf, int len, int flags)
	Receive data on already connected socket.
int	recvfrom (int sock, char *buf, int len, int flags, SOCKADDR *from, int *fromlen)
	Receive data from endpoint node.
int	closesocket (int sock)
	Close socket and release socket descriptor.
int	getpeername (int sock, SOCKADDR *name, int *namelen)
	Retrieve IP address and port number of the endpoint node.
int	getsockname (int sock, SOCKADDR *name, int *namelen)
	Retrieve local IP address and port number.
int	ioctlsocket (int sock, long cmd, unsigned long *argp)
	Control IO mode of a socket.
HOSTENT *	gethostbyname (const char *name, int *err)
	Retrieve host IP address from host name.

Description

BSD socket routines enable BSD compliant communication over TCP/IP.

The BSD sockets application programming interface (API) is a set of standard function calls that can be used in an application. They allow programmers to add Internet communication to their products.

BSD sockets is not a stand-alone socket solution, but it is an API that relies on other socket communication for data exchange. Thus, you always need to add TCP and UDP to your project if you wish to use BSD sockets.

Note

More information on the usage of BSD and how to work with the functions is available at BSD Socket.

---

Data Structure Documentation

struct SOCKADDR

Generic Socket Address structure.

/ Generic Socket Address structure

Parameter for:

• accept, bind, connect, getpeername, getsockname, recvfrom, sendto

Data Fields
int8_t	sa_data	Direct address (up to 14 bytes)
uint16_t	sa_family	Address family.

struct IN_ADDR

Generic IPv4 Address structure.

Parameter for:

• SOCKADDR_IN structure

Data Fields
union IN_ADDR	__unnamed__

union IN_ADDR.__unnamed__

Data Fields
__unnamed__	__unnamed__
__unnamed__	__unnamed__
uint32_t	s_addr	IP address in network byte order.

struct IN_ADDR.__unnamed__.__unnamed__

Data Fields
uint8_t	s_b1
uint8_t	s_b2
uint8_t	s_b3
uint8_t	s_b4	IP address, byte access.

struct SOCKADDR_IN

IPv4 Socket Address structure.

Used in:

• bind, connect, sendto

Data Fields
IN_ADDR	sin_addr	IP address.
int16_t	sin_family	Socket domain.
uint16_t	sin_port	Port.
int8_t	sin_zero	reserved

struct HOSTENT

BSD Host Entry structure.

Returned by:

• gethostbyname

Data Fields
char **	h_addr_list	Pointer to an array of IPv4 addresses.
int16_t	h_addrtype	Address Type: AF_INET, AF_NETBIOS.
char **	h_aliases	Pointer to an array of alias names.
int16_t	h_length	Length of address in bytes.
char *	h_name	Official name of host.

Function Documentation

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

Accept connect request for a listening socket.

Parameters

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

Returns

status information:

• Socket descriptor identification number or
• BSD_ERROR_SOCKET = Socket invalid.
• BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode.
• BSD_ERROR_CLOSED = Remote node has closed the connection.

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 if the system detects RTX 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.

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

//----------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//----------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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;
      }
      if (dbuf[0] == BLINKLED) {
        LED_Out (dbuf[1]);
      }
    }
    closesocket (sock);
  }
}

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

Assign a local address and port to a socket.

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:

• BSD_SUCCESS = Operation successful.
• BSD_ERROR_SOCKET = Socket invalid.
• BSD_ERROR_PARAMETER = Invalid or not supported parameters.

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.

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

//----------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//----------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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;
      }
      if (dbuf[0] == BLINKLED) {
        LED_Out (dbuf[1]);
      }
    }
    closesocket (sock);
  }
}

int closesocket

(

int

sock

)

Close socket and release socket descriptor.

Parameters

[in]

sock

socket descriptor obtained with socket.

Returns

status information:

• BSD_SUCCESS = Operation successful.
• BSD_ERROR_SOCKET = Socket invalid.
• BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode.
• BSD_ERROR_LOCKED = Socket is locked by another task.

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 if the system detects RTX 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.

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

//---------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//---------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res, addrlen;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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) {
    addrlen = sizeof (addr);
      res = recvfrom (sock, dbuf, sizeof (dbuf), 0, addr, &addrlen);
      if (res <= 0) {
        break;
      }
      procrec ((uint8_t *)dbuf);
      printf ("Remote IP: %d.%d.%d.%d\n",addr.sin_addr.s_b1,
                                         addr.sin_addr.s_b2,
                                         addr.sin_addr.s_b3,
                                         addr.sin_addr.s_b4);
      printf ("Remote port: %d\n",ntohs (addr.sin_port));
    }
    closesocket (sock);
  }
}

int connect	(	int	sock,
		SOCKADDR *	addr,
		int	addrlen
	)

Connect a socket to a remote host.

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:

• BSD_SUCCESS = Operation successful.
• BSD_ERROR_SOCKET = Socket invalid or in invalid state.
• BSD_ERROR_PARAMETER = Invalid or not supported parameters.
• BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode.
• BSD_ERROR_CLOSED = Remote node has closed the connection.
• BSD_ERROR = Error in underlying native socket.

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 if the system detects RTX 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.

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

//----------------------------------------------------------------------------
//  Thread 'Client': BSD Client socket process
//----------------------------------------------------------------------------
static void Client (void const *arg) {
  SOCKADDR_IN addr;
  int sock, res;
  char dbuf[4];
  uint8_t p2val,lshf;
 
  while (1) {
    sock = socket (AF_INET, SOCKTYPE, 0);

    addr.sin_port      = htons(PORT_NUM);
    addr.sin_family    = PF_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));

    lshf  = 1;
    p2val = 0x01;
    while (1) {
      // Shift the LEDs 
      LED_Out (p2val);
      p2val = lshf ? (p2val << 1) : (p2val >> 1);
      if (p2val == 0x80) lshf = 0;
      if (p2val == 0x01) lshf = 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);
  }
}

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

Retrieve host IP address from host name.

Parameters

[in]	name	host name.
[out]	err	returned error code: BSD_SUCCESS = Operation successful. BSD_ERROR_LOCKED = Function is locked by another task. BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode. BSD_ERROR_PARAMETER = Invalid parameter. BSD_ERROR_NONAME = Host name does not exist. BSD_ERROR_TIMEOUT = DNS server response timeout. BSD_ERROR = Generic error.

Returns

status information:

• HOSTENT result structure or
• 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

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
};
 
static void dns_task (void) {
  int i, j, err;
  HOSTENT *host;
  IN_ADDR *addr;
 
  for (i = 0; ; i++) {
    if (!hosts[i]) i = 0;
    printf ("Host: %s\n",hosts[i]);

    host = gethostbyname (hosts[i], &err);
    if (host == NULL) {
      if (err == SCK_ENONAME) {
        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: %d.%d.%d.%d\n",addr->s_b1,
                                           addr->s_b2,
                                           addr->s_b3,
                                           addr->s_b4);
      }
    }
    os_dly_wait (300);
  }
}

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

Retrieve IP address and port number of the endpoint node.

Parameters

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

Returns

status information:

• BSD_SUCCESS = Operation successful.
• BSD_ERROR_SOCKET = Socket invalid.
• BSD_ERROR = Socket is not created.

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.

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

//---------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//---------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res, addrlen;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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) {
    addrlen = sizeof (addr);
      res = recvfrom (sock, dbuf, sizeof (dbuf), 0, addr, &addrlen);
      if (res <= 0) {
        break;
      }
      procrec ((uint8_t *)dbuf);
    getpeername (sock, (SOCKADDR *)&addr, &addrlen);
      printf ("Remote IP: %d.%d.%d.%d\n",addr.sin_addr.s_b1,
                                         addr.sin_addr.s_b2,
                                         addr.sin_addr.s_b3,
                                         addr.sin_addr.s_b4);
      printf ("Remote port: %d\n",ntohs (addr.sin_port));
    }
    closesocket (sock);
  }
}

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

Retrieve local IP address and port number.

Parameters

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

Returns

status information:

• BSD_SUCCESS = Operation successful.
• BSD_ERROR_SOCKET = Socket invalid.
• BSD_ERROR = Socket is not created.

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.

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

//---------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//---------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, res, addrlen;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, SOCK_DGRAM, IPPROTO_UDP);

    addr.sin_port        = htons(1001);
    addr.sin_family      = PF_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: %d.%d.%d.%d\n",addr.sin_addr.s_b1,
                                      addr.sin_addr.s_b2,
                                      addr.sin_addr.s_b3,
                                      addr.sin_addr.s_b4);
    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);
  }
}

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

Control IO mode of a socket.

Parameters

[in]	sock	socket descriptor obtained with socket.
[in]	cmd	command to perform: FIONBIO = enable non-blocking mode. FIO_DELAY_ACK = enable delay-ack. FIO_KEEP_ALIVE = enable keep-alive mode. FIO_FLOW_CTRL = enable flow-control mode.
[in]	argp	command's parameter

Returns

status information:

• BSD_SUCCESS = Operation successful.
• BSD_ERROR_SOCKET = Socket invalid.
• BSD_ERROR_PARAMETER = Invalid or not supported parameters.
• BSD_ERROR = Socket is not created.

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 in the RTX environment.

Code Example

//---------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//---------------------------------------------------------------------------
static void Server (void const *arg) {
  int 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 == SCK_SUCCESS) {
    printf ("Nonblocking mode enabled.\n");
  }
  else {
    printf ("ioctlsocket() error\n!");
  }
  ..
}

int listen	(	int	sock,
		int	backlog
	)

Set a socket in a listening mode.

Parameters

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

Returns

status information:

• BSD_SUCCESS = Operation successful.
• BSD_ERROR_SOCKET = Socket invalid.
• BSD_ERROR_PARAMETER = Invalid or not supported parameters.
• BSD_ERROR = Not enough sockets available for 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 queued.

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

//----------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//----------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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;
      }
      if (dbuf[0] == BLINKLED) {
        LED_Out (dbuf[1]);
      }
    }
    closesocket (sock);
  }
}

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

Receive data on already connected socket.

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 or
• BSD_ERROR_SOCKET = Socket invalid or in invalid state.
• BSD_ERROR_CLOSED = Remote node has closed the connection.
• BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode.
• BSD_ERROR_TIMEOUT = Wait for data timeout in blocking mode.
• BSD_ERROR_LOCKED = Socket is locked by another task.

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 if the system detects RTX 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.

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

//----------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//----------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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;
      }
      if (dbuf[0] == BLINKLED) {
        LED_Out (dbuf[1]);
      }
    }
    closesocket (sock);
  }
}

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

Receive data from endpoint node.

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, or NULL for none
[out]	fromlen	length of SOCKADDR structure.

Returns

status information:

• Number of bytes received or
• BSD_ERROR_SOCKET = Socket invalid or in invalid state.
• BSD_ERROR_CLOSED = Remote node has closed the connection.
• BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode.
• BSD_ERROR_TIMEOUT = Wait for data timeout in blocking mode.
• BSD_ERROR_LOCKED = Socket is locked by another task.

Note

Parameters from and fromlen are ignored for SOCK_STREAM socket type.

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 if the system detects RTX 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.

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

//----------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//----------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res, addrlen;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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) {
    addrlen = sizeof (addr);
      res = recvfrom (sock, dbuf, sizeof (dbuf), 0, addr, &addrlen);
      if (res <= 0) {
        break;
      }
      procrec ((uint8_t *)dbuf);
      printf ("Remote IP: %d.%d.%d.%d\n",addr.sin_addr.s_b1,
                                         addr.sin_addr.s_b2,
                                         addr.sin_addr.s_b3,
                                         addr.sin_addr.s_b4);
      printf ("Remote port: %d\n",ntohs (addr.sin_port));
    }
    closesocket (sock);
  }
}

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

Send data on already connected socket.

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 or
• BSD_ERROR_SOCKET = Socket invalid or in invalid state.
• BSD_ERROR_PARAMETER = Invalid or not supported parameters.
• BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode.
• BSD_ERROR_CLOSED = Remote node has closed the connection.
• BSD_ERROR = Error in underlying native socket.
• BSD_ERROR_LOCKED = Socket is locked by another task.

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 if the system detects RTX environment, this function returns after the data has been successfully transmitted.
• In non blocking mode, the function returns immediately without blocking the system. Return value represents the number of bytes sent, which can be less than len, if the data can not be transmitted in one packet.

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

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

//----------------------------------------------------------------------------
//  Thread 'Client': BSD Client socket process
//----------------------------------------------------------------------------
static void Client (void const *arg) {
  SOCKADDR_IN addr;
  int sock, res;
  char dbuf[4];
  uint8_t p2val,lshf;
 
  while (1) {
    sock = socket (AF_INET, SOCKTYPE, 0);

    addr.sin_port      = htons(PORT_NUM);
    addr.sin_family    = PF_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));

    lshf  = 1;
    p2val = 0x01;
    while (1) {
      // Shift the LEDs 
      LED_Out (p2val);
      p2val = lshf ? (p2val << 1) : (p2val >> 1);
      if (p2val == 0x80) lshf = 0;
      if (p2val == 0x01) lshf = 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);
  }
}

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

Send data to endpoint node.

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 or
• BSD_ERROR_SOCKET = Socket invalid or in invalid state.
• BSD_ERROR_PARAMETER = Invalid or not supported parameters.
• BSD_ERROR_WOULDBLOCK = Function would block in non-blocking mode.
• BSD_ERROR_CLOSED = Remote node has closed the connection.
• BSD_ERROR = Error in underlying native socket.
• BSD_ERROR_LOCKED = Socket is locked by another task.

Note

Parameters to and tolen are ignored for SOCK_STREAM socket type.

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:

• In blocking mode, which is enabled if the system detects RTX environment, this function returns after the data has been successfully transmitted.
• In non blocking mode, the function returns immediately without blocking the system. Return value represents the number of bytes sent, which can be less than len, if the data can not be transmitted in one packet.

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.

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

//----------------------------------------------------------------------------
//  Thread 'Client': BSD Client socket process
//----------------------------------------------------------------------------
static void Client (void const *arg) {
  SOCKADDR_IN addr;
  int sock, res;
  char dbuf[4];
  uint8_t p2val,lshf;
 
  while (1) {
    sock = socket (AF_INET, SOCKTYPE, 0);

    addr.sin_port      = htons(PORT_NUM);
    addr.sin_family    = PF_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));

    lshf  = 1;
    p2val = 0x01;
    while (1) {
      // Shift the LEDs 
      LED_Out (p2val);
      p2val = lshf ? (p2val << 1) : (p2val >> 1);
      if (p2val == 0x80) lshf = 0;
      if (p2val == 0x01) lshf = 1;
    
      // Send the data to LED Server. 
      dbuf[0] = BLINKLED;
      dbuf[1] = p2val;
      res = sendto (sock, (char *)&dbuf, 2, 0, (SOCKADDR *)&to, sizeof (to));
      if (res < 0) {
        break;
      }
      osDelay (100 * SPEED);
    }
    closesocket (sock);
  }
}

int socket	(	int	family,
		int	type,
		int	protocol
	)

Create a communication endpoint called socket.

Parameters

[in]	family	address family: AF_INET = address family internet.
[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 identification number or
• BSD_ERROR_PARAMETER = Invalid or not supported parameters.
• BSD_ERROR = Allocate socket failed.

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

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

//----------------------------------------------------------------------------
//  Thread 'Server': BSD Server socket process
//----------------------------------------------------------------------------
static void Server (void const *arg) {
  SOCKADDR_IN addr;
  int sock, sd, res;
  int type = (int)arg;
  char dbuf[4];
 
  while (1) {
    sock = socket (AF_INET, type, 0);

    addr.sin_port        = htons(PORT_NUM);
    addr.sin_family      = PF_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;
      }
      if (dbuf[0] == BLINKLED) {
        LED_Out (dbuf[1]);
      }
    }
    closesocket (sock);
  }
}