NI XNET Sockets Functions

Sockets Functions

• nxaccept
• nxbind
• nxclose
• nxconnect
• nxFD_CLR
• nxFD__SET
• nxFD_ZERO
• nixnet_addr
• nixnet_aton
• nixnet_ntoa
• nixnet_ntop
• nixnet_pton
• nxlisten
• nxfreeaddrinfo
• nxgetaddrinfo
• nxgetlasterrornum
• nxgetlasterrorstr
• nxgetnameinfo
• nxgetpeername
• nxgetsockname
• nxgetsockopt
• nxrecv
• nxrecvfrom
• nxselect
• nxsend
• nxsendto
• nxsetsockopt
• nxshutdown
• nxsocket
• nxstrerr_r

nxaccept

Purpose

Accepts a connection on a socket.

Format

nxSOCKET NI_CDECL nxaccept( nxSOCKET socket, struct nxsockaddr *addr, nxsocklen_t *addrlen);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

struct nxsockaddr *addr: Specifies the address to the socket. Typically, an nxsockaddr_storage structure or protocol-specific structure (nxsockaddr_in for IPv4 addresses) is passed for this parameter and cast into an nxsockaddr pointer.

nxsocklen_t *addrlen: Specifies the size, in bytes, of the address structure pointed to by nxsockaddr.

Outputs

Return Value

On success, a file descriptor for the new socket is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxbind

Purpose

Binds a name to a socket.

Format

int32_t NI_CDECL nxbind( nxSOCKET socket, const struct nxsockaddr *name, nxsocklen_t namelen);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

const struct nxsockaddr *name: Specifies the address to the socket. Typically, an nxsockaddr_storage structure or protocol-specific structure (nxsockaddr_in for IPv4 addresses) is passed for this parameter and typecast to an nxsockaddr pointer.

nxsocklen_t namelen: Specifies the size, in bytes, of the address structure pointed to by nxsockaddr.

Outputs

Return Value

On success, a file descriptor for the new socket is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxclose

Purpose

Closes a socket.

Format

int32_t NI_CDECL nxclose( nxSOCKET socket);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

Outputs

Return Value

On success, zero is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxconnect

Purpose

Initiates a connection on a socket.

Format

int32_t NI_CDECL nxconnect( nxSOCKET socket, const struct nxsockaddr *name, nxsocklen_t namelen);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

const struct nxsockaddr *name: Specifies the address to the socket. Typically, an nxsockaddr_storage structure or protocol-specific structure (nxsockaddr_in for IPv4 addresses) is passed for this parameter and typecast to an nxsockaddr pointer.

nxsocklen_t namelen: Specifies the size, in bytes, of the address structure pointed to by nxsockaddr.

Outputs

Return Value

On success, zero is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxFD_CLR

Purpose

Removes the file descriptor fd from the set.

Format

int32_t NI_CDECL nxfd_isset( nxSOCKET socket, nxfd_set *set);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

nxfd_set *set: Adds a file descriptor to set to specify an array of nxSOCKETs.

Outputs

Return Value

If the specified nxfd_set contains the socket socket, then 1 is returned. Otherwise, 0 is returned.

nxFD_ZERO

Purpose

Removes all sockets from the set. Use this macro as a first step to initialize a file descriptor set.

Format

void nxFD_ZERO( nxfd_set *set

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

nxfd_set *set: Adds a file descriptor to set to specify an array of nxSOCKETs.

Outputs

Return Value

If the specified nxfd_set contains the socket socket, then 1 is returned. Otherwise, 0 is returned.

nxlisten

Purpose

Listens for connections on a socket.

Format

int32_t NI_CDECL nxlisten( nxSOCKET socket, int32_t backlog);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

int32_t backlog: Defines the maximum length to which the queue of pending connections for the socket can grow. If a connection request arrives when the queue is full, the client might receive an error with an indication of nxECONNREFUSED or, if the underlying protocol supports retransmission, the request might be ignored so that a later reattempt at connection succeeds.

Outputs

Return Value

On success, zero is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxfreeaddrinfo

Purpose

Frees the memory that was allocated for the dynamically allocated linked list res by nxgetaddrinfo.

Format

void NI_CDECL nxfreeaddrinfo( struct nxaddrinfo *res );

Inputs

struct nxaddrinfo *res: Specifies the pointer to the head of the linked list res allocated by nxgetaddrinfo. This memory will be freed and the pointer becomes invalid after calling this function.

nxgetaddrinfo

Purpose

Returns one or more addrinfo structures, each of which contains an Internet address that can be specified in a call to nxbind or nxconnect.

Format

int32_t NI_CDECL nxgetaddrinfo( nxIpStackRef_t stackRef, const char *node, const char *service, const struct nxaddrinfo *hints, struct nxaddrinfo **res );

Inputs

nxIpStackRef_t stack_ref: The stackRef parameter references the IP Stack to use for the creation of this socket. This reference is returned from nxIpStackCreate or nxIpStackOpen.

const char *node: Identifies the string notation of the remote address. Currently DNS lookups are not supported, so node must be a valid IP address string.

const char *service: Identifies the remote port number

const struct nxaddrinfo *hints: The hints argument points to an nxaddrinfo structure that specifies criteria for selecting the socket address structures returned in the list pointed to by res.

The nxaddrinfo structure contains the following fields:

Field	Description
int32_t ai_flags;	Options for nxgetaddrinfo.
int32_t ai_family;	Address family
int32_t ai_socktype;	Socket type
int32_t ai_protocol;	Protocol type
socklen_t ai_addrien;	Length of ai_addr in bytes.
struct nxsockaddr ai_addr	Host address
char ai_canonname;	Cannonical name of the host
struct nxaddrinfo ai_next;	Pointer to next item in the linked list (or null).

struct nxaddrinfo **res: Creates a pointer to a new nxaddrinfo structure with the information requested after successful completion of the function.

Outputs

Return Value

On success, one or more nxaddrinfo structures are returned, each of which contains an IP address that can be specified in a call to nxbind or nxconnect. On error, nxgetaddrinfo returns the error number, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxgetlasterrornum

Purpose

Retrieves the value of the calling thread's last-error code.

Format

int32_t NI_CDECL nxgetlasterrornum(void);

Inputs

N/A

Outputs

Return Value

Calling thread's last-error code value.

Description

The nxgetlasterrornum function retrieves the calling thread's last-error code value. The last-error code is maintained on a per-thread basis. Multiple threads do not overwrite each other's last-error code.

nxgetlasterrorstr

Purpose

Retrieves the last error produced by the calling thread.

Format

char* NI_CDECL nxgetlasterrorstr( char* buf, size_t buflen);

Inputs

char* buf: Creates a buffer to display the error code string.

size_t buflen: Specifies in bytes the length of the buffer.

Outputs

Return Value

The most recent error produced by the calling thread is returned.

Description

Returns the most recent error as a string. If buf is nullptr, or if buflen ≤1, then buf is not modified. If the error string is longer than buflen, then the error string is returned truncated (buflen - 1).

nxgetnameinfo

Purpose

Converts a socket address to a corresponding host in a protocol-independent manner.

Format

int32_t NI_CDECL nxgetnameinfo( nxIpStackRef_t stackRef, const struct nxsockaddr *addr, nxsocklen_t addrlen, char *host, nxsocklen_t hostlen, char *serv, nxsocklen_t servlen, int32_t flags );

Inputs

nxIpStackRef_t stack_ref: The stackRef parameter references the IP Stack to use for the creation of this socket. This reference is returned from nxIpStackCreate or nxIpStackOpen.

const struct nxsockaddr *addr: Specifies the remote IP address.

nxsocklen_t addrlen: Specifies the size, in bytes, of the address structure pointed to by nxsockaddr.

char *host: Pointer to the buffer in which the hostname will be stored. You can specify that no hostname is required by providing a NULL host argument. However, at least one hostname or service name must be requested. DNS lookup is not supported; therefore, the hostname will be the address.

nxsocklen_t hostlen: The size, in bytes, of the buffer in which the hostname will be stored. You can specify that no hostname is required by providing a 0 hostlen argument. However, at least one hostname or service name must be requested.

char *serv: Pointer to the buffer in which the service name will be stored. You can specify that no service name is required by providing a NULL serv argument. However, at least one hostname or service name must be requested.

nxsocklen_t servlen: The size, in bytes, of the buffer in which the service name will be stored. You can specify that no service name is required by providing a 0 servlen argument. However, at least one hostname or service name must be requested.

int32_t flags: Specifies the type of message reception. The flags argument can be zero or multiple flags (bitwise OR). Valid flags are dependent upon the socket protocol (TCP or UDP).

Outputs

Return Value

On success, 0 is returned, and node and service names, if requested, are filled with null-terminated strings, possibly truncated to fit the specified buffer lengths. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxgetpeername

Purpose

Returns the name of the connected peer socket.

Format

int32_t NI_CDECL nxgetpeername( nxSOCKET socket, struct nxsockaddr *addr, nxsocklen_t *addrlen);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

struct nxsockaddr *addr: Specifies the socket address of the connected socket.

nxsocklen_t *addrlen: Specifies the size, in bytes, of the address structure pointed to by nxsockaddr.

Outputs

Return Value

On success, zero is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxgetsockname

Purpose

Returns the current address to which the socket is bound.

Format

int32_t NI_CDECL nxgetsockname( nxSOCKET socket, struct nxsockaddr *addr, nxsocklen_t *addrlen);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

struct nxsockaddr *addr: Specifies the socket address.

nxsocklen_t *addrlen: Specifies the size, in bytes, of the address structure pointed to by nxsockaddr.

Outputs

Return Value

On success, zero is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxgetsockopt

Purpose

Use to get options for the socket referenced by the file descriptor nxsocket.

Format

int32_t NI_CDECL nxgetsockopt( nxSOCKET socket, int32_t level, int32_t optname, void *optval, nxsocklen_t *optlen );

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

int32_t level: Specifies the level at which the option you are calling resides. To use an option at the socket API level, the value is nxSOL_SOCKET. To use options at any other level, you must supply the protocol number for the protocol that controls the option. For example, to indicate that an option is to be interpreted by the TCP protocol, set level to be the protocol number of TCP.

int32_t optname: Specifies the name of the option to be used to be used with the socket.

void *optval: Identifies the buffer in which the value for the requested option(s) is to be returned.

nxsocklen_t *optlen: Indicates the size of the buffer identified by optval.

Outputs

Return Value

On success, zero is returned for the standard options. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

Options

IP protocol supports some protocol-specific socket options that can be set with nxsetsockopt and read with nxgetsockopt.

nxrecv

Purpose

Used to receive a message from a socket.

Format

int32_t NI_CDECL nxrecv( nxSOCKET socket, void *mem, int32_t len, int32_t flags);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

void *mem: Pointer to a buffer to place received data.

int32_t len: Returns the length in bytes of the message.

int32_t flags: Specifies the type of message reception. The flags argument can be zero or multiple flags (bitwise OR). Valid flags are dependent upon the socket protocol (TCP or UDP).

Outputs

Return Value

On success, these calls return the number of bytes received. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxrecvfrom

Purpose

Used to receive a message from a socket.

Format

int32_t NI_CDECL nxrecvfrom( nxSOCKET socket, void *mem, int32_t len, int32_t flags, struct nxsockaddr *from, nxsocklen_t *fromlen);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

void *mem: Pointer to a buffer to place received data.

int32_t len: Returns the length in bytes of the message.

int32_t flags: Specifies the type of message reception. The flags argument can be zero or multiple flags (bitwise OR). Valid flags are dependent upon the socket protocol (TCP or UDP).

struct nxsockaddr *from: Returns the IP address of the source.

nxsocklen_t *fromlen: Specifies the length of the address.

Outputs

Return Value

On success, these calls return the number of bytes received. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxselect

Purpose

Enables a program to monitor multiple sockets.

Format

int32_t NI_CDECL nxselect( int32_t nfds, nxfd_set *readfds, nxfd_set *writefds, nxfd_set *exceptfds, nxtimeval *timeout);

Inputs

int32_t nfds: Ignored. This parameter is included for compatibility with BSD-style sockets.

nxfd_set *readfds: Collects a set of sockets to monitor until they become ready for reading. A socket is ready for reading if a read operation will not block; in particular, a socket is also ready on end-of-file.

After nxselect has returned, readfds will be cleared of all sockets except for those that are ready for reading.

nxfd_set *writefds: Collects a set of sockets to monitor until they become ready for writing. A file descriptor is ready for writing if a write operation will not block. However, even if a file descriptor indicates as writable, a large write could still block.

After nxselect has returned, writefds will be cleared of all sockets except for those that are ready for writing.

nxfd_set *exceptfds: Collects a set of sockets to monitor for exceptional conditions (e.g., out-of-band data on a TCP socket).

After nxselect() has returned, exceptfds will be cleared of all sockets except for those for which an exceptional condition has occurred.

nxtimeval *timeout: Specifies the interval that nxselect should block waiting for a socket.

The call will block until one of the following conditions are met:

• A socket becomes ready.
• The socket or owning IP stack is destroyed.
• The timeout expires.

The timeout interval is rounded up to the system clock granularity; kernel scheduling delays mean that the blocking interval may overrun by a small amount.

If both fields of the nxtimeval structure are zero, then nxselect returns immediately. (This is useful for polling.)

If timeout is specified as NULL, nxselect blocks indefinitely waiting for a file descriptor to become ready.

Outputs

Return Value

On success, nxselect returns the number of sockets contained in the returned descriptor sets readfds, writefds, and exceptfds. The return value may be zero if the timeout expired before any sockets became ready. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

Description

The following macros are provided for modifying sets of sockets:

nxFD_ZERO  initialilzes a file descriptor set nxfd_set after removing all sockets from the set.

nxFD_SET  adds a file descriptor fd to a descriptor set.

nxFD_CLR  removes a particular file descriptor fd from a descriptor set.

nxFD_ISSET  returns nonzero if the file descriptor fd is present in the set, otherwise a zero is returned.

nxsend

Purpose

Transmits a message to another socket.

Format

int32_t NI_CDECL nxsend( nxSOCKET socket, const void *dataptr, int32_t size, int32_t flags);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

const void *dataptr: Pointer to the TCP data in the buffer.

int32_t size: Specifies the size of the message in bytes.

int32_t flags: Specifies flags for data transmission. The flags argument can be zero or multiple flags (bitwise OR). Valid flags are dependent upon the socket protocol (TCP or UDP).

Outputs

Return Value

On success, the number of bytes sent is returned.On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxsendto

Purpose

Transmits a message to another socket.

Format

int32_t NI_CDECL nxsendto( nxSOCKET socket, const void *dataptr, int32_t size, int32_t flags, const struct nxsockaddr *to, nxsocklen_t tolen);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

const void *dataptr: Pointer to the data to send.

int32_t size: Specifies the size of the data to send.

int32_t flags: Specifies flags for data transmission. The flags argument can be zero or multiple flags (bitwise OR). Valid flags are dependent upon the socket protocol (TCP or UDP).

const struct nxsockaddr *to: Specifies the destination address.

nxsocklen_t tolen: Specifies the length of the address.

Outputs

Return Value

On success, the number of bytes sent is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxsetsockopt

Purpose

Use nxsetsockopt to set options for the socket referenced by the file descriptor nxsocket.

Format

int32_t NI_CDECL nxsetsockopt( nxSOCKET socket, int32_t level, int32_t optname, const void *optval, nxsocklen_t optlen );

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

int32_t level: Specifies the level at which the option you are calling resides. To use an option at the socket API level, the value is nxSOL_SOCKET. To use options at any other level, you must supply the protocol number for the protocol that controls the option. For example, to indicate that an option is to be interpreted by the TCP protocol, set level to be the protocol number of TCP.

int32_t optname: Specifies the name of the option to be used to be used with the socket.

const void *optval: Identifies the buffer in which the value for the requested option(s) is to be returned.

nxsocklen_t optlen: Indicates the size of the buffer identified by optval.

Outputs

Return Value

On success, zero is returned for the standard options. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

Options

IP protocol supports some protocol-specific socket options that can be set with nxsetsockopt and read with nxgetsockopt.

Refer to Socket Options for a list of available options.

nxshutdown

Purpose

Shuts down part of a full-duplex connection.

Format

int32_t NI_CDECL nxshutdown( nxSOCKET socket, int32_t how);

Inputs

nxSOCKET socket: Specifies the file descriptor for the socket.

int32_t how: Specifies the activity to be shut down on the connection; how is enumerated list of values, as represented in the following table:

Enumeration	Value	Description
nxSHUT_RD	0	Further receptions will be disallowed.
nxSHUT_WR	1	Further transmissions will be disallowed.
nxSHUT_RDWR	2	Further receptions and transmissions will be disallowed.

Outputs

Return Value

On success, zero is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxsocket

Purpose

Creates an endpoint for communication.

Format

nxSOCKET NI_CDECL nxsocket( nxIpStackRef_t stack_ref, int32_t domain, int32_t type, int32_t protocol);

Inputs

nxIpStackRef_t stack_ref: The stackRef parameter references the IP Stack to use for the creation of this socket. This reference is returned from nxIpStackCreate or nxIpStackOpen.

int32_t domain: Specifies a communication domain; this selects the protocol family that will be used for communication. These families are defined in nxsocket.h. NI-XNET currently supports nxAF_INET.

int32_t type: Specifies the communication semantics. NI-XNET currently supports the following socket types:

Type	Description
nxSOCK_STREAM	Provides sequenced, reliable, two-way, connection-based byte streams. (TCP)
nxSOCK_DGRAM	Provides connectionless, unreliable messages of fixed maximum length. (UDP)
int32_t protocol

Specifies a particular protocol to be used with the socket. Typically, only a single protocol supports a particular socket type within a given protocol family, in which case protocol can be specified as 0. However, it is possible that many protocols support the socket type, in which case a particular protocol must be specified in this manner. The protocol number to use is specific to the "communication domain" in which communication is to take place. Valid values are:

Protocol	Protocol Number
nxIPPROTO_IP	0
nxIPPROTO_TCP	6
nxIPPROTO_UDP	8
nxIPPROTO_IPV6	12

Outputs

Return Value

On success, a file descriptor for the new socket is returned. On error, -1 is returned, and nxgetlasterrornum or nxgetlasterrorstr can retrieve the error code.

nxstrerr_r

Purpose

Returns a string that describes the error code.

Format

char* NI_CDECL nxstrerr_r( int errnum, char* buf, size_t buflen);

Inputs

int errnum: Specifies the error code or number.

char* buf: Allocates a buffer that is filled by the function.

size_t buflen: Specifies in bytes the length of the buffer.

Outputs

Return Value

The nxstrerr_r function returns the appropriate error description string, or an "Unknown error" message if the error number is unknown. If the error string is longer than buflen, then the error string is returned truncated (buflen - 1).