	RSA BSAFE Micro Edition Suite	Streamlined security for mobile and embedded devices

Functions

This section documents the functions that are provided for SIO operations.

Typedefs
typedef int R_CDECL	SIO_GETHOSTBYADDR_CB_T (unsigned char addr, int alen, char name, int len)
	The prototype for a callback that can be used to replace the `gethostbyaddr()` function. More...
typedef int R_CDECL	SIO_GETHOSTBYNAME_CB_T (char name, unsigned char addr, int alen)
	The prototype for a callback that can be used to replace the `gethostbyname()` function. More...
Functions
int R_CDECL	SIO_sock_should_retry (SIO_SOCK sock)
	Indicates whether the last I/O operation (read or write) should be retried. More...
int R_CDECL	SIO_conn_should_retry (SIO_SOCK sock)
	Indicates whether the connection should be retried. More...
int R_CDECL	SIO_sock_non_fatal_error (int error)
	Indicates that if the error error occurs it should be considered a non-fatal error. More...
int R_CDECL	SIO_conn_non_fatal_error (int error)
	Determines whether the error code error is fatal or whether the operation may be retried for a socket pending connection. More...
int R_CDECL	SIO_fd_should_retry (int sock)
	Indicates whether the last I/O operation (read or write) should be retried. More...
int R_CDECL	SIO_fd_non_fatal_error (int error)
	Indicates that if the error error occurs it should be flagged as a non-fatal error. More...
int R_CDECL	SIO_shutdown (SIO_SOCK fd, int mode)
	Shuts down the socket identified by the file descriptor fd. More...
int R_CDECL	SIO_close (SIO_SOCK fd)
	Closes the file descriptor fd. More...
int R_CDECL	SIO_gethostbyname (char name, unsigned char addr, int alen)
	Returns the network address relating to the host name name. More...
int R_CDECL	SIO_gethostbyaddr (unsigned char addr, int alen, char name, int nlen)
	Takes a network address addr and attempts to determine the matching host name. More...
void R_CDECL	SIO_set_gethostbyname (SIO_GETHOSTBYNAME_CB_T *func)
	Sets the callback used by SIO_gethostbyname(). More...
SIO_GETHOSTBYNAME_CB_T* R_CDECL	SIO_get_gethostbyname ()
	Returns the callback used by SIO_gethostbyname(). More...
void R_CDECL	SIO_set_gethostbyaddr (SIO_GETHOSTBYADDR_CB_T *func)
	Sets the callback used by SIO_gethostbyaddr(). More...
SIO_GETHOSTBYADDR_CB_T* R_CDECL	SIO_get_gethostbyaddr ()
	Returns the callback used by SIO_gethostbyaddr(). More...
int R_CDECL	SIO_sock_error (SIO_SOCK sock)
	Returns the last socket error code for the socket sock. More...
int R_CDECL	SIO_socket_nbio (SIO_SOCK fd, int mode)
	Sets the value of the non-blocking I/O flag for the socket descriptor underlying a socket descriptor. More...
int R_CDECL	SIO_get_port (char str, unsigned short port_ptr)
	Converts a port number or service name in ASCII format into a port number. More...
int R_CDECL	SIO_get_host_ip (char str, unsigned char addr, int alen)
	Converts a host name or IP address in standard dot notation (that is, `192.168.1.1`) into an IP address suitable for use with standard network routines. More...
SIO_SOCK R_CDECL	SIO_get_accept_socket (char *host_port, int bind_mode)
	Creates a socket setup for incoming connections on the server side. More...
SIO_SOCK R_CDECL	SIO_accept (SIO_SOCK sock, char **ip_port)
	Accepts the next pending connection on the socket sock. More...
SIO_SOCK R_CDECL	SIO_connect (char host, char port, int nbio, SIO_SOCK *sockp)
	Establishes a connection to a server application at host listening on port. More...
int R_CDECL	SIO_sock_init (void)
	Initializes the system network library for use by applications. More...
void R_CDECL	SIO_sock_cleanup (void)
	Performs clean up operations for all sockets and is called when no additional sockets will be used. More...
int R_CDECL	SIO_set_tcp_nodelay (SIO_SOCK sock, int turn_on)
	Sets the socket option `TCP_NODELAY` (in a system header file) for the socket descriptor underlying a socket. More...
int R_CDECL	SIO_ghbn_default (char name, unsigned char addr, int alen)
	Takes a host name name and attempts to determine the matching network address. More...
int R_CDECL	SIO_ghbn_cache (char name, unsigned char addr, int alen)
	Uses the cache to obtain the socket address from the host name. More...
int R_CDECL	SIO_ghba_default (unsigned char addr, int alen, char name, int nlen)
	Takes a network address addr and attempts to determine the matching host name. More...
int R_CDECL	SIO_ghbn_cache_cleanup (void)
	Clears the cache created when any `gethostbyname` operations are performed. More...
int R_CDECL	SIO_host_to_addr (char host, char addr, int *addrlen)
	Returns the socket address corresponding to the host specified by host. More...
int R_CDECL	SIO_getsockopt (int socket, int level, int option_name, void option_value, unsigned long option_len)
	Retrieves the value for the option specified for the supplied socket. More...
int R_CDECL	SIO_setsockopt (int socket, int level, int option_name, void *option_value, unsigned long option_len)
	Sets the value for the option specified for the supplied socket. More...
int R_CDECL	SIO_getsockname (int socket, struct sockaddr address, unsigned long address_len)
	Retrieves the locally-bound name of the specified socket and stores the information in the supplied structure. More...

Typedef Documentation

typedef int R_CDECL SIO_GETHOSTBYADDR_CB_T(unsigned char *addr, int alen, char *name, int len)

The prototype for a callback that can be used to replace the gethostbyaddr() function.
Parameters:

addr [In] The network address of the host.

alen [In] The length of the network address.

name [Out] The name of the host.

len [In] The length of the buffer for the host name.

Returns:
The length of the host name copied into name if successful.
0 indicates error.

typedef int R_CDECL SIO_GETHOSTBYNAME_CB_T(char *name, unsigned char *addr, int alen)

The prototype for a callback that can be used to replace the gethostbyname() function.
Parameters:

name [In] The name of the host whose address is being retrieved.

addr [Out] The network address of the host.

alen [In] The length of the buffer supplied for addr.

Returns:
The length of the data copied into addr if successful.
0 indicates error.

Function Documentation

SIO_SOCK R_CDECL SIO_accept ( SIO_SOCK sock,

char ** addr

) ;

Accepts the next pending connection on the socket sock. This function is used by a server application to complete the establishment of a socket connection with a client application.
Parameters:

sock [In] The socket.

addr [Out] The string pointer to the IP port.

Returns:
The socket to use for reading and writing over the newly-established connection.
INVALID_SOCKET indicates error.

No value is returned if addr is NULL.
Otherwise the IP address and port of the connected node is copied to this buffer in the form IP address:port (for example, 192.168.1.1:4433).
Memory is allocated if *addr == NULL.
See also:
SIO_get_accept_socket() and SIO_connect().
Samples:
sock_server.c.

int R_CDECL SIO_close ( SIO_SOCK fd ) ;

Closes the file descriptor fd.
Parameters:

fd [In] The file descriptor.

Returns:
1 indicates success.
<=0 indicates error.
Samples:
simple.c, sock_client.c, and sock_server.c.

int R_CDECL SIO_conn_non_fatal_error ( int error ) ;

Determines whether the error code error is fatal or whether the operation may be retried for a socket pending connection.
Parameters:

error [In] The error number.

Returns:
1 indicates the error was successfully set to non-fatal.
<= 0 indicates error.

The value of error is the last return code from a network I/O operation.
See also:
SIO_conn_should_retry() and SIO_sock_non_fatal_error().

int R_CDECL SIO_conn_should_retry ( SIO_SOCK sock ) ;

Indicates whether the connection should be retried. This is used with non-blocking I/Os to distinguish between a temporary failure to complete an operation and an error.
Parameters:

sock [In] The return code from the last I/O operation.

Returns:
1 indicates to retry.
<= 0 indicates not to retry.
See also:
SIO_conn_non_fatal_error(), SIO_sock_non_fatal_error() and SIO_sock_should_retry().

SIO_SOCK R_CDECL SIO_connect ( char * host,

char * port,

int nbio,

SIO_SOCK * sockp

) ;

Establishes a connection to a server application at host listening on port.
Parameters:

host [In] The host name (or hostname:port).

port [In] The port (may be NULL).

nbio [In] 0 indicates blocking I/O.
Otherwise non-blocking I/O.

sockp [Out] The socket pointer (created socket returned) or a pointer to a file descriptor variable.

Returns:
>0 indicates the connection socket number (if not a NULL pointer).
<= 0 indicates error. One of:

SIO_R_CONNECT_ERROR.
SIO_R_ERROR_SETTING_NBIO.
SIO_R_NO_HOSTNAME_SPECIFIED.
SIO_R_NO_PORT_SPECIFIED.
SIO_R_UNABLE_TO_CREATE_SOCKET.

If port is specified as part of host (that is, hostname:port), it takes precedence over any port set via port.
When performing a non-blocking connect, a valid sockp must be provided. Otherwise the function returns an error code if the connect does not complete immediately and there is no other way to access the socket descriptor created.
The warning ERR_R_SHOULD_RETRY indicates a delayed connection on a non-blocking socket.

See also:
SIO_accept() and SIO_get_accept_socket().
Samples:
simple.c, and sock_client.c.

int R_CDECL SIO_fd_non_fatal_error ( int error ) ;

Indicates that if the error error occurs it should be flagged as a non-fatal error.
Parameters:

error [In] The error code.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
SIO_fd_should_retry().

int R_CDECL SIO_fd_should_retry ( int sock ) ;

Indicates whether the last I/O operation (read or write) should be retried. This is used with non-blocking I/Os to distinguish between a temporary failure to complete an operation and an error.
Parameters:

sock [In] The file descriptor.

Returns:
1 indicates should retry.
<= 0 indicates should not retry.
See also:
SIO_fd_non_fatal_error().

SIO_SOCK R_CDECL SIO_get_accept_socket ( char * host_port,

int bind_mode

) ;

Creates a socket setup for incoming connections on the server side. This function combines calls to socket, bind and listen.
Parameters:

host_port [In] The local address.

bind_mode [In] The socket bind mode.
See Identifiers for valid values.

host_port is of the form hostname:port. When hostname is a wildcard address, this allows incoming connections on all network interfaces.
Returns:
>= 0 indicates the socket file descriptor.
-1 indicates invalid socket. One of:

SIO_R_UNABLE_TO_BIND_SOCKET.
SIO_R_UNABLE_TO_CREATE_SOCKET.
SIO_R_UNABLE_TO_LISTEN_SOCKET.
See also:
SIO_accept() and SIO_connect().
Samples:
sock_server.c.

SIO_GETHOSTBYADDR_CB_T* R_CDECL SIO_get_gethostbyaddr ( ) ;

Returns the callback used by SIO_gethostbyaddr().
Returns:
A pointer to the gethostbyaddr callback.
NULL indicates there is no callback.
See also:
SIO_set_gethostbyaddr() and SIO_gethostbyaddr().

SIO_GETHOSTBYNAME_CB_T* R_CDECL SIO_get_gethostbyname ( ) ;

Returns the callback used by SIO_gethostbyname().
Returns:
A pointer to the gethostbyname callback.
NULL indicates there is no callback set.
See also:
SIO_set_gethostbyname() and SIO_gethostbyname().

int R_CDECL SIO_get_host_ip ( char * str,

unsigned char * addr,

int alen

) ;

Converts a host name or IP address in standard dot notation (that is, 192.168.1.1) into an IP address suitable for use with standard network routines.
Parameters:

str [In] The host name.

addr [In] The host address.

alen [In] The host address length.

Returns:
The length of the address data copied into addr.
0 indicates error.
The error stack indicates the error reason. One of:

Error Reason Description

SIO_R_INVALID_IP_ADDRESS Returned if IP address passed in is invalid.

SIO_R_BAD_HOSTNAME_LOOKUP Returned if hostname lookup fails.

See also:
SIO_gethostbyname().

int R_CDECL SIO_get_port ( char * str,

unsigned short * port_ptr

) ;

Converts a port number or service name in ASCII format into a port number.
Parameters:

str [In] The port or service name.

port_ptr [Out] The port pointer.

Returns:
The port number.
See also:
SIO_get_host_ip().

int R_CDECL SIO_gethostbyaddr ( unsigned char * addr,

int alen,

char * name,

int nlen

) ;

Takes a network address addr and attempts to determine the matching host name.
Parameters:

addr [In] The host address.

alen [In] The host address length.

name [Out] The host name.

nlen [In] The host name length.

Returns:
>0 indicates the length of the host name that is copied into name.
<=0 indicates error.

The callback used to implement SIO_gethostbyaddr() can be replaced by using SIO_set_gethostbyaddr().
See also:
SIO_gethostbyname() and SIO_get_host_ip().
Samples:
cache_server.c, p7ssl_server.c, and ssl_server.c.

int R_CDECL SIO_gethostbyname ( char * name,

unsigned char * addr,

int alen

) ;

Returns the network address relating to the host name name.
Parameters:

name [In] The host name.

addr [Out] The output buffer.

alen [In] The output buffer length.

Returns:
The length of the address data copied into addr.
0 indicates error.

If alen is too small, the error stack will contain the error code ERR_R_BUFFER_TOO_SMALL.

The callback used to implement SIO_gethostbyname() can be replaced by using SIO_set_gethostbyname().

int R_CDECL SIO_getsockname ( int socket,

struct sockaddr * address,

unsigned long * address_len

) ;

Retrieves the locally-bound name of the specified socket and stores the information in the supplied structure.
Parameters:

socket [In] The socket from which to read the address.

address [Out] The structure where the address is stored.

address_len [In, Out] The maximum length of the address data is passed in.
The length used is passed out.

Returns:
0 indicates success.
-1 indicates error.

If the size of the address value is greater than address_len, the value stored in the object pointed to by the address argument will be silently truncated. If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.
Samples:
cache_server.c, p7ssl_server.c, and ssl_server.c.

int R_CDECL SIO_getsockopt ( int socket,

int level,

int option_name,

void * option_value,

unsigned long * option_len

) ;

Retrieves the value for the option specified for the supplied socket.
Parameters:

socket [In] The socket from which to read the option.

level [In] The protocol level at which the option resides.

option_name [In] The option to retrieve.
See sys/socket.h for valid values.

option_value [Out] The destination for the option data value.

option_len [In, Out] The maximum length of value data is passed in.
The length used is passed out.

Returns:
0 indicates success.
-1 indicates error.

If the size of the option value is greater than option_len, the value stored in the object pointed to by the option_value argument will be silently truncated. Otherwise, the object pointed to by the option_len argument will be modified to indicate the actual length of the value.
Samples:
bio_client.c, nbio_client.c, sock_client.c, and ssl_client.c.

int R_CDECL SIO_ghba_default ( unsigned char * addr,

int alen,

char * name,

int len

) ;

Takes a network address addr and attempts to determine the matching host name.
Parameters:

addr [In] The host address.

alen [In] The host address length.

name [Out] The host name.

len [In] The host name length.

Returns:
>0 indicates the length of the host name that is copied into name.
<=0 indicates error.

int R_CDECL SIO_ghbn_cache ( char * name,

unsigned char * addr,

int alen

) ;

Uses the cache to obtain the socket address from the host name. If the host name does not appear in the cache, the address is obtained using the normal functions and added to the cache.
Parameters:

name [In] The cache name.

addr [Out] The address of the cache.

alen [In] The address length.

Returns:
1 indicates success.
0 indicates error.

This function is only used for Internet addresses.
See also:
SIO_ghbn_cache_cleanup().

int R_CDECL SIO_ghbn_cache_cleanup ( ) ;

Clears the cache created when any gethostbyname operations are performed. The cache stores host name to socket address mappings. Because the cache store is global, this function must be called at the end of the program.

Returns:
1 indicates success.
0 indicates error.
See also:
SIO_ghbn_cache().

int R_CDECL SIO_ghbn_default ( char * name,

unsigned char * addr,

int len

) ;

Takes a host name name and attempts to determine the matching network address.
Parameters:

name [In] The host name.

addr [Out] The host address.

len [In] The host address length.

Returns:
>0 indicates the length of the host name that is copied into name.
<=0 indicates error.

int R_CDECL SIO_host_to_addr ( char * host,

char * addr,

int * addrlen

) ;

Returns the socket address corresponding to the host specified by host. The address is returned in addr with the length of the address returned in addrlen. This function is used to obtain the address to bind.
Parameters:

host [In] The host name.

addr [Out] The host address.

addrlen [Out] The length of the address.

Returns:
1 indicates success.
<=0 indicates error.

Passing addr returns the length of the socket address.

void R_CDECL SIO_set_gethostbyaddr ( SIO_GETHOSTBYADDR_CB_T * cb ) ;

Sets the callback used by SIO_gethostbyaddr().
Parameters:

cb [In] A callback for gethostbyaddr that can be used to provide this function to the library on platforms where it may not be supported.

Passing NULL indicates that no callback will be available until a valid function is set and future calls to SIO_gethostbyaddr() will fail.
See also:
SIO_get_host_ip() and SIO_gethostbyaddr().

void R_CDECL SIO_set_gethostbyname ( SIO_GETHOSTBYNAME_CB_T * cb ) ;

Sets the callback used by SIO_gethostbyname().
Parameters:

cb [In] A callback for gethostbyname that can be used to provide this function to the library on platforms where it may not be supported.

Passing NULL will mean there is no gethostbyname callback. Until a valid function is set all future calls to SIO_gethostbyname() will fail.
See also:
SIO_get_gethostbyname() and SIO_gethostbyname().

int R_CDECL SIO_set_tcp_nodelay ( SIO_SOCK sock,

int turn_on

) ;

Sets the socket option TCP_NODELAY (in a system header file) for the socket descriptor underlying a socket. TCP normally sends data when it is presented. When outstanding data has not yet been acknowledged, TCP gathers small amounts of output to be sent in a single packet once an acknowledgment is received. This packetization may cause significant delays. This function controls this behavior (that is, enabled or disabled).
Parameters:

sock [In] The socket.

turn_on [In] The requested no_delay mode. One of:

1 indicates enabled (that is, on).
0 indicates disabled (that is, off).

Returns:
1 indicates success.
<= 0 indicates error.

If this call fails because it is not supported on the current platform the error stack will contain the error ERR_R_NOT_SUPPORTED.
See also:
SIO_socket_nbio() and SIO_socket_ioctl().

int R_CDECL SIO_setsockopt ( int socket,

int level,

int option_name,

void * option_value,

unsigned long option_len

) ;

Sets the value for the option specified for the supplied socket.
Parameters:

socket [In] The socket from which to read the option.

level [In] The protocol level at which the option resides.

option_name [In] The option to set.
See sys/socket.h for valid values.

option_value [Out] The destination for the option data value.

option_len [In] The length of the option data.
The length used is passed out.

Returns:
0 indicates success.
-1 indicates error.
Samples:
bio_client.c, nbio_client.c, sock_client.c, and ssl_client.c.

int R_CDECL SIO_shutdown ( SIO_SOCK fd,

int mode

) ;

Shuts down the socket identified by the file descriptor fd.
Parameters:

fd [In] The socket file descriptor.

mode [In] Specifies the type of shutdown. One of the shutdown types in sys/socket.h:
Shutdown Type Description

SHUT_RD Indicates disable further send and receive operations.

SHUT_RDWR Indicates disable further send and receive operations.

SHUT_WR Indicates disable further send operations.

Returns:
0 indicates success.
< 0 indicates error.
See also:
SIO_close().

void R_CDECL SIO_sock_cleanup ( ) ;

Performs clean up operations for all sockets and is called when no additional sockets will be used.
See also:
SIO_sock_init().

int R_CDECL SIO_sock_error ( SIO_SOCK sock ) ;

Returns the last socket error code for the socket sock.
Parameters:

sock [In] The socket descriptor.

Returns:
The socket error code.

int R_CDECL SIO_sock_init ( ) ;

Initializes the system network library for use by applications.
Returns:
1 indicates success.
<= 0 indicates error.

This function only performs initialization on the required platforms.
See also:
SIO_shutdown().

int R_CDECL SIO_sock_non_fatal_error ( int error ) ;

Indicates that if the error error occurs it should be considered a non-fatal error.
Parameters:

error [In] The error code.

Returns:
1 indicates success.
<= 0 indicates error.
See also:
SIO_conn_should_retry() and SIO_conn_non_fatal_error().

int R_CDECL SIO_sock_should_retry ( SIO_SOCK sock ) ;

Indicates whether the last I/O operation (read or write) should be retried. This is used with non-blocking I/Os to distinguish between a temporary failure to complete an operation and an error.
Parameters:

sock [In] The return code from the last I/O operation.

Returns:
1 indicates should retry.
<= 0 indicates should not retry.
See also:
SIO_conn_should_retry().

int R_CDECL SIO_socket_nbio ( SIO_SOCK sock,

int mode

) ;

Sets the value of the non-blocking I/O flag for the socket descriptor underlying a socket descriptor.
Parameters:

sock [In] The file descriptor.

mode [In] The socket descriptor mode. One of:

1 indicates non-blocking I/O.
0 indicates blocking I/O.

Returns:
1 indicates success.
<= 0 indicates error.

If this call fails because it is not supported on the current platform the error stack will contain the error ERR_R_NOT_SUPPORTED.
See also:
SIO_set_tcp_nodelay() and SIO_socket_ioctl().

Functions

Typedefs

Functions

Typedef Documentation

Function Documentation