Name

dtrap ()

Syntax

void dtrap (void);

Parameters

None.

Description

The dtrap() routine is called by the debug version of embTCP whenever it detects a situation that should not be occurring. The function prints the message "dtrap" and then goes into a forever loop. In general, you should eliminate or understand all causes of a call to dtrap before moving on to the release version of the code.

Returns

Nothing

Notes

• dtrap() resides in embsrc/tcpdata.c and should be modified to suit the needs of the application developer.
• In Debug-mode, embTCP will not call dtrap().

Name

panic()

Syntax

void panic(char *msg)

Parameters

Description

The panic() routine is called if the software detects a fatal system error. It will print and error message, call dtrap() in the debug version, and then call exit(1). You may want to add code to this routine to attempt to restart the system.

Returns

Never

Name

in_v4addrcfg ()

Syntax

int in_v4addrcfg(char *name, char *addr, char *subnet_mask, char *gateway, uint32_t flags);

Parameters

Description

This function is used to provide addressing information for an interface. It is only expected to be invoked at startup time (from user_pre_setup() in tcpdata.c). If the system uses DHCP (as indicated via the 'flags' parameter), all of the address parameters can be specified as zero.

Returns

This function returns EFAILURE if the interface name is incorrect or if any of the address strings cannot be parsed successfully. Otherwise, it returns ESUCCESS.

Name

upnp_callback()

Syntax

void upnp_callback(char *name, int status);

Parameters

Description

The upnp_callback() routine is the registered callback handler for the IPv4 address acquisition manager. It will be called to indicate the result of address acquisition. The default version of this routine prints a status message in DEBUG mode, and does nothing in release mode. The following is the definition of upnbp_callback(). The user may add any desired functionality to this routine.

Returns

Nothing.

Name

PING_CBKFN (typedef)

Syntax

typedef void (*PING_CBKFN)(ip_addr src, char *buffer, int length, uint16_t id, uint16_t seq, bool_t match, int reason, void *pio);

Parameters

Description

The ping application client's callback function is invoked upon the receipt of an ICMP/IPv4 Echo Reply, or upon the expiration of a timeout or when the module is in the process of closing (via ping_close()). In the latter two cases, the packet parameter will be NULL.

Returns

Nothing

Name

dnc_free_hostent()

Syntax

void dnc_free_hostent(struct hostent *hep);

Parameters

Description

This function frees a hostent structure that was previously allocated via a call to gethostbyname().

Returns

Nothing

Name

dnc_init()

Syntax

int dnc_init(void);

Parameters

None

Description

This function initializes the DNS client module.

Returns

This function can return any one of the following values:

• ENP_PARAM, if the configuration provided is not correct
• ENP_RESOURCE, if the DNS client couldn't allocate memory for the DNS client table, or if any of the t_socket(), t_bind(), and t_setsockopt() calls failed
• ESUCCESS, if the DNS client was initialized successfully

Name

dnc_shutdown()

Syntax

void dnc_shutdown(void);

Parameters

None

Description

This function shuts down the DNS client module. It releases all resources allocated by that module. All subsequent name resolution requests will fail.

Returns

Nothing

Name

gethostbyname()

Syntax

struct hostent *gethostbyname(char *name);

Parameters

Description

This function is used to obtain the IPv4 address corresponding to a host name.

Returns

This function NULL if the resolution fails. Otherwise, it returns a pointer to a dynamically allocated hostent data structure containing (among other things) the IPv4 address that corresponds to the name.

Name

if_freenameindex()

Syntax

void if_freenameindex(struct if_nameindex *ptr);

Parameters

Description

This function frees a previously allocated array of struct if_nameindex structures (that was created via a call to if_nameindex()).

Returns

Nothing

Name

if_indextoname()

Syntax

char *if_indextoname(unsigned int ifindex, char *ifname);

Parameters

Description

This function converts a ones-based interface index into the corresponding interface name.

Returns

This function returns its second parameter ('ifname'). It returns NULL in the event of an error.

Name

if_nameindex()

Syntax

struct if_nameindex *if_nameindex(void);

Parameters

None

Description

This function creates and returns a dynamically allocated array of struct if_nameindex structures representing the various interfaces present in the system.

Returns

Pointer to the first element in the dynamically allocated array of struct if_nameindex structures.

Name

if_nametoindex

Syntax

unsigned int if_nametoindex(const char *ifname);

Parameters

Description

This function converts an interface name (e.g., "et1") into the corresponding ones-based interface index.

Returns

This function returns the ones-based interface index. If the interface does not exist, it returns 0.

Name

in_addrconf_acquire()

Syntax

int in_addrconf_acquire(char *name, uint32_t flags);

Parameters

Description

This function starts the address acquisition process for the specified interface using the protocols specified in the 'flags' parameter.

Returns

This function returns ESUCCESS if the address acquisition process was initiated successfully; otherwise, it returns EFAILURE.

Name

in_addrconf_release()

Syntax

int in_addrconf_release(char *name, uint32_t flags, bool_t restore_static);

Parameters

Description

This function terminates the use of the specified protocols for address acquisition on the specified interface. The interface address configuration data structures may also be cleared out.

Returns

This function returns ESUCCESS if the address release process was initiated successfully; otherwise, it returns EFAILURE.

Name

in_clrstats()

Syntax

int in_clrstats(int module_id, void *parm);

Parameters

Description

This function clears the statistics data structure for the specified module.

Returns

This function returns ENP_PARAM if the module identifier is not valid, or if the parameter pointer is NULL when clearing the interface module's statistics. It returns ENP_LOGIC if the caller requests clearing of queue- or socket-related statistics. Otherwise, it returns ESUCCESS.

Notes

• See function in_getstats() for discussion of table and parameter identifiers and example.

Name

in_clrtab()

Syntax

int in_clrtab(int modid, int tabid);

Parameters

Description

This function is used to clear the ARP cache or the DNS client table in the TCP/IP stack.

Returns

This function returns ENP_PARAM if the module identifier or table identifier is not valid. Otherwise, it returns ESUCCESS.

Notes

• See function in_getstats() for discussion of table and parameter identifiers and example.

Name

in_getparm()

Syntax

int in_getparm(int modid, int parmid, void *valp);

Parameters

Description

This function retrieves the value of the specified TCP/IP stack configuration parameter into the storage provided via 'valp'.

Returns

This function returns ENP_PARAM if any of the input parameters fails validation. Otherwise, it returns ESUCCESS.

Notes

• See function in_getstats() for discussion of table and parameter identifiers and example.

Name

in_getstats()

Syntax

int in_getstats(int modid, void *statp);

Parameters

Description

This function retrieves the statistics data structure for the specified module.

Example:

int
ut_arpstats(void)
{
   struct arp_stats arpstats;
   int rc;

   rc = in_getstats(ARP_MODULE, &arpstats);
   printf("ut_arpstats: in_getstats() returned %d\n", rc);

   if (rc == ESUCCESS) {
      printf("arpReqsIn:           %lu\n", arpstats.arpReqsIn);
      printf("arpReqsOut:          %lu\n", arpstats.arpReqsOut);
      printf("arpRepsIn:           %lu\n", arpstats.arpRepsIn);
      printf("arpRepsOut:          %lu\n", arpstats.arpRepsOut);
      printf("arpGratReqsConflict: %lu\n", arpstats.arpGratReqsConflict);
      printf("arpGratRepsConflict: %lu\n", arpstats.arpGratRepsConflict);
   }

   return (rc);
}

Notes

• Each module in the system has an identifier associated with it. The complete list of module identifiers is available in stkdata.h.
• Each configurable parameter in the system has an identifier associated with it. The complete list of parameter identifiers is available in stkdata.h.
• Two tables (ARP cache and DNS client) in the system have table identifiers associated with each one of them, and can be cleared. The complete list of table identifiers is available in stkdata.h.

Returns

This function returns ENP_PARAM if the module identifier is not valid, or if the pointer to the statistics data structure is NULL, or if the socket type field is invalid when the caller requests socket-related statistics. Otherwise, it always returns ESUCCESS.

Name

in_setparm()

Syntax

int in_setparm(int modid, int parmid, void *valp);

Parameters

Description

This function sets the value of the specified TCP/IP stack configuration parameter from data provided via 'valp'.

Returns

This function returns ENP_PARAM if any of the input parameters fails validation. Otherwise, it returns ESUCCESS.

Notes

• See function in_getstats() for discussion of table and parameter identifiers and example.

Name

inet_ntop()

Syntax

const char *inet_ntop(int af, const void *addr, char *str, size_t size);

Parameters

Description

This functions converts a binary representation of an IPv4 address (in network byte order) into a string in dotted decimal notation. The output buffer must be at least 16 bytes long.

Returns

This function returns NULL if it encountered an error; otherwise, it returns the third argument ('str').

Name

inet_pton()

Syntax

int inet_pton(int af, const char *src, void *dst);

Parameters

Description

This functions converts a string containing an IPv4 address in dotted decimal notation into its equivalent binary representation (in network byte order).

Returns

This function returns 0 if the conversion was successful. A non-zero return value indicates a failure.

Name

ping_close()

Syntax

void ping_close(void);

Parameters

None

Description

This function shuts down the ping application module. It releases all resources allocated by that module. All subsequent outbound ping requests will fail.

Returns

Nothing

Name

ping_init()

Syntax

int ping_init(void);

Parameters

None

Description

This function initializes the ping module. It allocates a buffer that will contain the ping session table, and also sets the size of the session table.

Returns

This function can return any one of the following values:

• ENP_RESOURCE, if the ping session table could not be allocated
• ENP_PARAM, if the size of the table is not greater than zero
• ESUCCESS, if the table was successfully setup

Name

ping_send()

Syntax

int ping_send(ip_addr dest, char *data, int length, uint16_t id, uint16_t seq, PING_CBKFN cbkp, void *pio);

Parameters

Description

This function creates and transmits an ICMP/IPv4 Echo packet.

Returns

This function returns ESUCCESS or a negative error code.

Name

t_socket()

Syntax

long t_socket (int domain, int type, int protocol);

Parameters

Description

t_socket() creates an endpoint for communication and returns a descriptor. The domain parameter specifies a communications domain within which communication will take place; this selects the protocol family which should be used. The protocol family generally is the same as the address family for the addresses supplied in later operations on the socket. These families are defined in the include file embtcp.h. The only currently understood format is:

AF_INET or PF_INET (ARPA Internet protocols)

The socket has the indicated type, which specifies the semantics of communication. Currently defined types are:

SOCK_STREAM      /* TCP*/
SOCK_DGRAM       /* UDP */

A SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams. A SOCK_DGRAM socket provides connectinless, unreliable data transfer to an application.

Sockets of type SOCK_STREAM are full-duplex byte streams, similar to pipes. A stream socket must be in a connected state before any data may be sent or received on it. A connection to another socket is created with a t_connect() call. Once connected, data may be transferred using t_send() and t_recv() calls. When a session has been completed, a t_socketclose() may be performed. Out-of-band data may also be transmitted as described in the t_send() page and received as described in t_recv().

The communications protocols used to implement a SOCK_STREAM ensure that data is not lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls will indicate an error with -1 returns and with ETIMEDOUT as the return code from t_errno(). An error is then indicated if no response can be elicited on an otherwise idle connection for a extended period (such as five minutes).

SOCK_DGRAM sockets allow sending of datagrams to correspondents named in t_sendto() calls. Datagrams are generally received with t_recvfrom(), which returns the next datagram with its return address.

The operation of sockets is controlled by socket level options. These options are defined in the file embtcp.h. t_getsockopt() and t_setsockopt() are used to get and set options, respectively.

Returns

A return value of -1 from t_socket() indicates failure. Any other return value indicates success.

See Also

t_accept, t_bind, t_connect, t_getsockname, t_getsockopt, t_listen, t_recv, t_select, t_send, t_shutdown

Name

t_listen()

Syntax

int t_listen(long s, int backlog);

Parameters

Description

To accept connections, a socket is first created with t_socket(), a backlog for incoming connections is specified with t_listen() and then the connections are accepted with t_accept(). The t_listen() call applies only to sockets of type SOCK_STREAM. The backlog parameter defines the maximum length for the queue of pending connections (not maximum open connections).

The computation is:

val = MIN(backlog, 5);
limit  =  3 * val / 2;

If a connection request arrives with the queue full the client will receive an error with an indication of ECONNREFUSED.

All incoming connection requests (such as those from a HTTP client (Web browser)) start off in the incomplete connection queue (when a TCP segment containing the SYN is received), and move to the completed connection queue after the successful completion of the three-way handshake. When the server application executes t_accept(), it will pick up the first available connection from the completed connection queue.

Returns

Returns 0 on success. On failure, it returns -1 and sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_accept, t_connect

Name

t_connect()

Syntax

int t_connect(long s, struct sockaddr *name, int namelen);

Parameters

Description

The parameter s is a socket. If it is of type SOCK_DGRAM, then this call specifies the peer with which the socket is to be associated; the address to which datagrams are sent and the only address from which datagrams are received. If it is of type SOCK_STREAM, then this call attempts to make a connection to another socket. The other socket is specified by name which is an address in the communications space of the socket. Each communications space interprets the name parameter in its own way.

Datagrams may use t_connect() multiple times to change their association. Datagram may also dissolve the association by connecting to an invalid address, such as a zero address.

Returns

This returns 0 on success. On failure, it returns -1 and sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_accept, t_connect, t_getsockname, t_select, t_socket

Name

t_socketclose()

Syntax

int t_socketclose(long s);

Note: this is just close() on traditional Sockets systems.

Parameters

Description

The t_socketclose() call causes all of a full-duplex connection on the socket associated with s to be shut down. Once a socket is closed, no further socket calls should be made with it.

Returns

This returns 0 on success. On failure, it returns -1.

See Also

t_accept, t_socket

Name

t_errno ()

Syntax

int t_errno(long s);

Parameters

Description

This function returns the error associated with the specified socket.

Returns

This function returns ENOTSOCK if the socket identifier is not valid.  Otherwise, it returns the error associated with the specified socket.

Name

t_select()

Syntax

int t_select (fd_set * readfds, fd_set * writefds, fd_set * exceptfds, long tv);

void FD_SET (long so, fd_set * set)

void FD_CLR (long so, fd_set * set)

void FD_ISSET (long so, fd_set * set)

void FD_ZERO (fd_set * set)

Parameters

Description

t_select() examines the socket descriptor sets whose addresses are passed in readfds, writefds, and exceptfds to see if some of their descriptors are ready for reading, ready for writing or have an exception condition pending. On return, t_select() replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. The total number of ready descriptors in all the sets is returned. Any of readfds, writefds, and exceptfds may be given as NULL pointers if no descriptors are of interest. Selecting true for reading on a socket descriptor upon which a t_listen() call has been performed indicates that a subsequent t_accept() call on that descriptor will not block.

In the standard Berkeley UNIX Sockets API, the descriptor sets are stored as bit fields in arrays of integers. This works in the UNIX environment because under UNIX socket descriptors are file system descriptors which are guaranteed to be small integers that can be used as indexes into the bit fields. In the embTCP stack, socket descriptor are pointers and thus a bit field representation of the descriptor sets is not feasible. Because of this, the embTCP Sockets API differs from the Berkeley standard in that the descriptor sets are represented as instances of the following structure:

typedef struct fd_set {      /* the select socket array manager */
   unsigned fd_count;      /* how many are SET? */
   long fd_array[FD_SETSIZE];   /* an array of SOCKETs */
} fd_set;

Instead of a socket descriptor being represented in a descriptor set via an indexed bit, an embTCP socket descriptor is represented in a descriptor set by its presence in the fd_array field of the associated fd_set structure. Despite this non-standard representation of the descriptor sets themselves, the following standard entry points are provided for manipulating such descriptor sets: FD_ZERO(&fdset) initializes a descriptor set fdset to the null set. FD_SET(fd, &fdset) includes a particular descriptor, fd, in fdset. FD_CLR(fd, &fdset) removes fd from fdset. FD_ISSET(fd, &fdset) is nonzero if fd is a member of fdset, zero otherwise. These entry points behave according to the standard Berkeley semantics.

The porting engineer should be aware that the value of FD_SETSIZE defines the maximum number of descriptors that can be represented in a single descriptor set. The default value of FD_SETSIZE of 12 is defined in emb_h/embtcp.h.

Another difference between the Berkeley and embTCP t_select() calls is the representation of the timeout parameter. Under Berkeley Sockets, the timeout parameter is represented by a pointer to a structure. Under embTCP Sockets, a timeout value is specified by the tv parameter, which defines the maximum number of millliseconds that should elapse before the call to t_select() returns. A tv parameter value of 0 implies that t_select() should return immediately (effectively a poll of the sockets in the descriptor set). The value INFINITE_DELAY is used to specify that t_select() block forever unless one of its descriptors becomes ready. The longest possible non-infinite delay is 0x7FFFFFFF milliseconds, which is about 24.86 days.

The final difference between the Berkeley and embTCP versions of t_select() is the absence in the embTCP version of the Berkeley width parameter. The width parameter is of use only when descriptor sets are represented as bit arrays and was thus deleted in the embTCP implementation.

Returns

t_select() returns a non-negative value on success. A positive value indicates the number of ready descriptors in the descriptor sets. 0 indicates that the time limit specified by tv expired.

See Also

t_accept, t_connect, t_listen, t_recv, t_send

Notes

Under rare circumstances, t_select() may indicate that a descriptor is ready for writing when in fact an attempt to write would block. This can happen if system resources necessary for a write are exhausted or otherwise unavailable. If an application deems it critical that writes to a file descriptor not block, it should set the descriptor for non-blocking I/O. See discussion of t_setsockopt.

Name

t_recv()

t_recvfrom()

Syntax

int t_recv(long s, char * buf, int len, int flags);

int t_recvfrom(long s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen);

Parameters

Description

s is a socket created with t_socket(). t_recv() and t_recvfrom() are used to receive messages from another socket. t_recv() may be used only on a connected socket (see t_connect), while t_recvfrom() may be used to receive data on a socket whether it is in a connected state or not.

If from is not a NULL pointer, the source address of the message is filled in. fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. The length of the message is returned. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see t_socket).

If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is non-blocking (see t_setsockopt) in which case -1 is returned with the external variable t_errno set to EWOULDBLOCK.

Note that t_recv() will return an EPIPE if an attempt is made to read from an unconnected socket.

The t_select() call may be used to determine when more data arrive.

The flags parameter is formed by OR-ing one or more of the following:

Returns

These calls return the number of bytes received, or -1 if an error occurred. On failure, they set an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_connect,t_getsockopt,t_select, t_send, t_socket

Name

t_send()

t_sendto()

Syntax

int t_send(long s, char *buf, int len, int flags);

int t_sendto(long s, char *buf, int len, int flags, struct sockaddr *to, int tolen);

Parameters

Description

t_send() and t_sendto() are used to transmit the message addressed by buf to another socket. t_send() may be used only when the socket is in a connected state, while t_sendto() may be used at any time, in which case the address of the target is given by the to parameter. The length of the message is given by len.

No indication of failure to deliver is implicit in a t_send(). Locally detected errors are indicated by a return value of -1.

If no messages space is available at the socket to hold the message to be transmitted, then t_send() normally blocks, unless the socket has been placed in non-blocking I/O mode. The t_select() call may be used to determine when it is possible to send more data.

The flags parameter may include one or more of the following:

#define MSG_OOB         0x1   /* process out-of-band data */

The flag MSG_OOB is used to send "out-of-band" data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support "out-of-band" data.

Returns

The call returns the number of characters sent, or -1 if an error occurred. On failure, it sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_recv, t_select, t_getsockopt, t_socket

Name

t_accept()

Syntax

long t_accept(long s, struct sockaddr *addr, int *addrlen);

Parameters

Description

The argument s is a socket that has been created with t_socket(), bound to an address with t_bind() and is listening for connections after a t_listen(). t_accept() extracts the first connection on the queue of pending connections, creates a new socket with the same properties as s and allocates a new file descriptor for the socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, t_accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, t_accept() returns an error as described below. The accepted socket is used to read and write data to and from the socket which connected to this one; it is not used to accept more connections. The original socket s remains open for accepting further connections.

The argument addr is a result parameter that is filled in with the address of the connecting entity as known to the communications layer, i.e. the exact format of the addr parameter is determined by the domain in which the communication is occurring. The addrlen is a value-result parameter. It should initially contain the amount of space pointed to by addr. On return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently with SOCK_STREAM.

It is possible to t_select() a socket for the purposes of doing an t_accept() by selecting it for read.

Returns

t_accept() returns a non-negative descriptor for the accepted socket on success. On failure, it returns -1 and sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_bind, t_connect, t_listen, t_select, t_socket

Name

t_bind()

Syntax

int t_bind(long s, struct sockaddr *name, int namelen);

Parameters

Description

t_bind() sets the local endpoint address and port number for a socket. When a socket is created with t_socket() it exists in a name space (address family) but has no name assigned. t_bind() requests that the name pointed to by name be assigned to the socket.

Returns

t_bind() returns 0 on success. On failure, it returns -1 and sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_connect, t_getsockname, t_listen, t_socket

Name

t_shutdown()

Syntax

int t_shutdown(long s, int how);

Parameters

Description

The t_shutdown() call causes all or part of a full-duplex connection on the socket associated with s to be shut down. If how is SHUT_RD, then further receives will be disallowed. If how is SHUT_WR, then further sends will be disallowed. If how is SHUT_RDWR, then further sends and receives will be disallowed.

Returns

This returns 0 on success. On failure, it returns -1 and sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_connect, t_socket

Name

t_getpeername()

Syntax

int t_getpeername(long s, struct sockaddr *name, int * addrlen);

Parameters

Description

Fills in the passed struct sockaddr with the IP addressing information of the connected host.

The addrlen is a value-result parameter and should initially contain the amount of space pointed to by name.

Returns

This returns 0 on success. On failure, it returns -1 and sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_bind, t_socket

Name

t_getsockname()

Syntax

int t_getsockname(long s, struct sockaddr *name, int * addrlen);

Parameters

Description

t_getsockname() returns the current name for the specified socket, in the passed struct sockaddr.

The addrlen is a value-result parameter and should initially contain the amount of space pointed to by name.

Returns

This returns 0 on success. On failure, it returns -1 and sets an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_bind, t_getpeername, t_socket

Name

t_getsockopt()

t_setsockopt()

Syntax

int t_getsockopt(long s, int level, int optname, char *optval, int optlen);

int t_setsockopt(long s, int level, int optname, char *optval, int optlen);

Parameters

Description

t_getsockopt() and t_setsockopt() manipulate options associated with a socket. The optname parameter identifies an option that is to be set with t_setsockopt() or retrieved with t_getsockopt().

The parameter optval is used to specify option values for t_setsockopt(). On calls to t_setsockopt() it generally contains a pointer to a variable or structure, the contents of which will define the value of the option to be set. On calls to t_getsockopt() it generally points to a variable or structure into which the value for the requested option is to be returned.

The following options are recognized by embTCP:

embTCP supports get/set operations for socket options as follows:

The include file embtcp.h contains definitions for option names, described below. Most options take a pointer to an int variable for optval. For t_setsockopt(), the variable addressed by the parameter should be non-zero to enable a Boolean option or zero if the option is to be disabled.

SO_LINGER uses a struct linger parameter defined in embtcp.h. This parameter specifies the desired state of the option and the linger interval (see below).

SO_REUSEADDR indicates that the rules used in validating addresses supplied in a t_bind() call should allow reuse of local addresses.

SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken. If the process is waiting in t_select() when the connection is broken, t_select() returns true for any read or write events selected for the socket.

SO_LINGER controls the action taken when unsent messages are queued on socket and a t_socketclose() is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the caller on the t_socketclose() attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the t_setsockopt() call when SO_LINGER is requested). If SO_LINGER is disabled and a t_socketclose() is issued, the system will process the close in a manner that allows the caller to continue as quickly as possible.

With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received. It will then be accessible with t_recv() calls without the MSG_OOB flag.

SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for the output and input buffers respectively. The buffer size may be increased for high-volume connections or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values.

SO_TYPE and SO_ERROR are options used only with t_getsockopt(). SO_TYPE returns the type of the socket, for example SOCK_STREAM. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors.

The TCP_NODELAY disables the Nagle algorithm, and prevents attempts to coalesce small packets less than the TCP_MSS, while awaiting acknowledgement for data already sent.

The options SO_NONBLOCK, SO_NBIO, and SO_BIO are unique to the InterNiche stack (these options do not appear in the Berkeley Sockets API) and are used to control whether a socket uses blocking or non-blocking IO.

SO_NBIO is used to specify that a socket use non-blocking IO. SO_BIO is used to specify that a socket use blocking IO. The use of t_setsockopt() to set these options is different than that of the standard Boolean options in that the value in optval is not used. All that is necessary is to specify the appropriate option name in optname.

Returns

The value returned for the SO_KEEPALIVE, SO_OOBINLINE, and SO_REUSEADDR socket options in a t_getsockopt() call is the corresponding bitmask (e.g., SO_KEEPALIVE (8), as defined in embtcp.h) if the option is enabled, and zero otherwise.

For all others, 0 is returned upon success. On failure, they return -1 and set an internal t_errno to one of the errors listed in Sockets Errors to indicate the error. The t_errno can be retrieved by a call to t_errno(s).

See Also

t_socket

Name

get_mac_address()

Syntax

int get_mac_address(int iface, uint8_t *emac);

Parameters

Description

The ethernet driver calls get_mac_address() to obtain the 48-bit MAC address of the hardware interface. The function obtains the 6-byte value from a user-defined location, such as non-volatile memory, and copies it into the array pointed to by the emac parameter.

Returns

The function returns 0 if the copy was successful, and -1 if there was a parameter error or the MAC address was unavailable.

Notes

For a chip with a single ethernet device, 0 is the only valid iface parameter value.

Name

emac_phy_init()

Syntax

int emac_phy_init(void);

Parameters

None.

Description

The ethernet driver calls emac_phy_init() to initialize the external PHY chip. In order to accomodate different PHY chips, the implementation of the initialization function is the responsibility of the porting engineer. A sample implementation for the DP83848C PHY chip is provided in phy_dp83848.c.

The initialization function should:

• reset the PHY chip
• configure the PHY chip
• bring up the Link layer of the network interface
• provide the link configuration information to the ethernet device driver.

If the link is successfully established, either through auto-negotiation or by programming the link speed and duplex mode, the emac_phy_init() function must call eth_setlink() to communicate the negotiated link characteristics to the ethernet device driver. Refer to the sample emac_phy_init() implementation for an example of the eth_setlink() call.

Returns

emac_phy_init() returns 0 if the PHY initialization was successful and a negative error code if the initialization failed. If the PHY initialization fails, the ethernet device initialization fails, and the ethernet interface is considered unavailable.

Notes

The PHY chip must be connected to the network in order to initialize the PHY using the auto-negotiation protocol.

The usleep function can be used to insert short delays into the initialization process. The delay is accomplished via a software loop. The loop parameters may need to be adjusted for the actual system clock speed.

Name

help - display information about a command

Syntax

help [-m STRING] [-c STRING]

Parameters

Description

This command provides helpful information about the CLI commands. If no parameters are entered, the list of available menu groups and the commands within each menu group is displayed. If a menu group is specified, information about the menu group and its commands are displayed. If a command is specified, information about the command is displayed. If the command name is a present in more than one menu group, the menu group name must also be specified to remove any ambiguity.

Notes/Status

• "help -m foo -c bar" is equivalent to "foo bar ?".
• Entering "?" is equivalent to entering "help".

arp

arp - Display ARP statistics

Syntax

arp [-z STRING]

Parameters

Description

This command displays the ARP table and the ARP statistics. If '-z STRING' is specified, the statistics are reset to zero after they are displayed.

Name

dhcstat - Display DHCP/auto-configuration-related information

Syntax

dhcstat

Parameters

None.

Description

This command displays the status of the DHCP, auto-configuration, and UPNP state machines.

Name

iface - Display network interface information

Syntax

iface [-i UINT [-m UINT]]

Parameters

Description

This command displays information about the specified Network Interface. If '-i' is not specified, the list of available Network Interfaces is displayed.

The value of the '-m' is used to set the maximum transmission unit of the selected interface. Valid values are 128 to 65535. Care must be taken when setting the value to ensure that the value matches the capabilities of the underlying hardware.

Notes/Status

• The first Network Interface number is 1.

Name

linkstats - Display link-specific information

Syntax

linkstats -i INT

Parameters

Description

This command displays Link information for the specified Network Interface. The Link information is device-specific, and is provided by the implementor of the Network Interface device driver.

Notes/Status

• The first Network Interface number is 1.

Name

netstat - display operational statistics

Syntax

netstat {-c [-p <protocol>]} -m -q {-s [-p <protocol>]}

Parameters

Description

This command displays status information for various network protocols or modules.

Notes/Status

• The protocol names can be specified in either lowercase or uppercase.
• The -p option is only intended for use with either the -c option or the -s option.
• When the -c option is used without a -p option, this command will display information about sockets for all protocols.
• When the -s option is used without a -p option, this command will display statistics for all protocols.

Name

nslookup - Find the IP address of a domain name

Syntax

nslookup -a STRING

Parameters

Description

This command calls DNS servers or relies on the stack's cache to retrieve the IP address records for a domain name, such as "www.iniche.com."

Notes/Status

• The setdnssrv command can be used to initialize the DNS Server addresses used in the DNS query.

Name

ping - Send ICMP requests

Syntax

ping -a <IP addr> [-n <number of pings>] [ -l <length of packets>]

Parameters

Description

This command sends an ICMP/IPv4 Echo packet. It verifies that the data in the response exactly matches the data in the request. It reports any mismatches.

Notes/Status

• Some echo servers limit the length of responses. The returned messages will be truncated to that length.

queues

queues - Display NicheStack packet queues

Syntax

queues

Parameters

Description

This command displays the current status of various resource queues. These queues include the receive packet queue (rcvdq), free packet queues (cb-#), the free mbuf queue (mfreeq) and the 'inuse' mbuf queue (mbufq).

Sample Output:

-> queues
Packet buffer free queues, total packets:120 (99840 bytes)
cb-1 Q0128: size:7680, head:00A5A9FC, tail:00A5A96C, len:60, min:57, max:60
cb-2 Q1536: size:92160, head:00A5E784, tail:00A5E73C, len:60, min:52, max:60
mfreeq: head:00A5D82C, tail:00A5D804, len:120, min:118, max:120
mbufq: head:00000000, tail:00000000, len:0, min:0, max:2
rcvdq: head:00000000, tail:00000000, len:0, min:0, max:3

Name

setip - manually set IPv4 address information

Syntax

setip -i INT [-a IPADDR] [-s IPADDR] [-g IPADDR] [-o] [-r] [-e] [-p STRING]

Parameters

Description

This command configures a Network Interface. The '-i' parameter selects the Network Interface to configure. The user can set the IPv4 address, network submask and gateway IP address. IP address are specified in the format: NNN.NNN.NNN.NNN, where NNN can range from 0 to 255. The format: NNN.NNN, is shorthand for NNN.0.0.NNN.

Changes to the Network Interface configuration are performed immediately; open connections are not flushed or closed. If only the '-i' parameter is specified, the current configuration settings are displayed.

Example

Here are some examples of how to use this command:

##configure a static IPv4 address
setip -i 1 -a 10.0.0.112 -s 255.255.255.0 -g 10.0.0.1

##configure interface #1 to obtain an IPv4 address via DHCP
setip -i 1 -o -p dhcpc

##configure interface #1 to obtain an IPv4 address via auto-configuration
setip -i 1 -o -p autoip

##configure interface #1 to obtain an IPv4 address via DHCP or auto-configuration
##in this case, the system first attempts to obtain an address via DHCP.  If that
##fails, it auto-configures itself with an address in the range from 169.254.1.0
##to 169.254.254.255.
setip -i 1 -o -p dhcpc,autoip

##terminate the use of DHCP on interface #1, and release address obtained via that protocol
setip -i 1 -r -p dhcpc

##terminate the use of DHCP and auto-configuration on interface #1, and revert back to a
##previously configured static address
setip -i 1 -r -p dhcpc,autoip -e

Notes/Status

• Setting incorrect values may cause the network interface to become unusable.

Name

setdnssrv - Sets the address of an available DNS server

Syntax

setdnssrv -i <number_of_server> -a <IPv4_server_address> -d

Parameters

Description

This command sets one of the DNS server addresses used by the DNS client, and can also be used to add or delete DNS servers from the system configuration.

The maximum number of DNS Serves supported by embTCP is 3.

Name

status - display system status

Syntax

status [-i] [-m] [-q] [-s]

Parameters

Description

This command displays information about various embTCP components.