• 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

Accepts a connection on a socket.

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

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.

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.

Binds a name to a socket.

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

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.

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.

Closes a socket.

int32_t NI_CDECL nxclose( nxSOCKET socket);

nxSOCKET socket: Specifies the file descriptor for the socket.

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

Initiates a connection on a socket.

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

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.

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

Removes the file descriptor fd from the set.

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

nxSOCKET socket: Specifies the file descriptor for the socket.

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

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

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

void nxFD_ZERO( nxfd_set *set

nxSOCKET socket: Specifies the file descriptor for the socket.

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

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

Listens for connections on a socket.

int32_t NI_CDECL nxlisten( nxSOCKET socket, int32_t backlog);

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.

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

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

void NI_CDECL nxfreeaddrinfo( struct nxaddrinfo *res );

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.

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

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

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.

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.

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

int32_t NI_CDECL nxgetlasterrornum(void);

N/A

Calling thread's last-error code value.

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.

Retrieves the last error produced by the calling thread.

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

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

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

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

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

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

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 );

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

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.

Returns the name of the connected peer socket.

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

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.

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

Returns the current address to which the socket is bound.

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

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.

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

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

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

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.

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

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

Used to receive a message from a socket.

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

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

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

Used to receive a message from a socket.

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

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.

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

Enables a program to monitor multiple sockets.

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

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.

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.

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.

Transmits a message to another socket.

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

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

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

Transmits a message to another socket.

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

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.

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

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

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

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.

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

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.

Shuts down part of a full-duplex connection.

int32_t NI_CDECL nxshutdown( nxSOCKET socket, int32_t how);

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.

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

Creates an endpoint for communication.

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

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

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.

Returns a string that describes the error code.

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

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.

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