VxWorks Network Programming: TCP, UDP, Sockets, zbuf and RPC

VxWorks Network Programming: TCP, UDP, Sockets, zbuf and RPC

Network programming is a fundamental part of embedded software development. In a VxWorks system, network communication enables applications to exchange data with remote computers, expose services, coordinate distributed components, and connect embedded devices to larger control and monitoring systems.

VxWorks provides several networking mechanisms, including the Berkeley socket API, TCP and UDP transport protocols, the zero-copy-oriented zbuf API, and Remote Procedure Call (RPC) facilities where supported by the installed development environment.

Choosing the appropriate mechanism depends on the application’s communication pattern, latency requirements, memory constraints, reliability needs, and software architecture.

This guide covers the essential networking concepts and demonstrates common VxWorks programming patterns, from socket creation and address configuration to UDP datagrams, concurrent TCP servers, socket options, buffer management, and RPC.

Version note: VxWorks networking interfaces and available components vary by release, network stack, and project configuration. Confirm the relevant headers, library availability, and API documentation for the target version before using these examples in production.

🌐 VxWorks Networking Fundamentals

#

Network programming allows applications to communicate across tasks, processors, embedded devices, and remote computers. Typical applications include telemetry collection, remote diagnostics, command interfaces, industrial controllers, and distributed real-time systems.

VxWorks network programming commonly involves three layers of functionality:

• Transport protocols: TCP and UDP define how application data is delivered between endpoints.
• Socket APIs: Berkeley sockets provide a programming interface for creating endpoints and sending or receiving network data.
• Higher-level communication frameworks: Facilities such as RPC can simplify communication by allowing an application to invoke remote procedures through generated stubs.

Network components

#

A typical networked application consists of a local application task, the VxWorks networking stack, a network interface, an IP network, and a remote endpoint.

The networking stack handles functions such as IP addressing, packet routing, transport processing, and delivery of received data to the appropriate socket.

The application generally interacts with sockets rather than constructing complete Ethernet, IP, or TCP packets directly.

Ports and endpoints

#

An IP address identifies a network interface or host destination, while a port identifies a transport-layer endpoint associated with an application service.

A TCP or UDP endpoint is commonly identified by the combination of:

• An IP address.
• A transport protocol, such as TCP or UDP.
• A port number.

For example, a server might listen for TCP connections on port 5001. A client connects to the server’s IP address and port, while its own local port is usually assigned automatically when needed.

TCP and UDP maintain separate port spaces. A TCP service and a UDP service can therefore use the same numeric port without being the same endpoint.

Port numbers range from 0 through 65535. The well-known range, 0–1023, is reserved for standard services, while other ranges have different allocation conventions. The range used for dynamically assigned client ports depends on the operating system and network-stack configuration; applications should not assume that a particular port range is universally reserved for ephemeral ports.

Packet encapsulation

#

When an application transmits data through a socket, the networking stack adds the protocol information needed to deliver it to the destination.

A simplified transmission path is:

1. The application creates or obtains its payload.
2. TCP or UDP processes the application data.
3. IP adds addressing and routing information.
4. The link layer constructs the appropriate network frame.
5. The receiving system processes the headers and delivers the payload to the destination socket.

This process is called encapsulation. On reception, the layers process the headers in the opposite direction.

Understanding encapsulation is useful when diagnosing packet loss, connection failures, address mismatches, and protocol-level interoperability problems.

🔌 Berkeley Socket Programming

#

Berkeley sockets provide a standard programming interface for network communication. A socket acts as an endpoint through which an application sends and receives data using a configured protocol.

VxWorks applications commonly use Internet-domain sockets for IPv4 communication, with the precise set of supported address families depending on the installed networking stack.

Socket types

#

The two most frequently used socket types are:

TCP is appropriate when the application requires an ordered byte stream and the transport layer’s reliability mechanisms. UDP is useful when datagram boundaries, low overhead, or application-controlled delivery behavior are important.

Neither protocol guarantees that the remote application will process a message. Applications requiring delivery confirmation or exactly-once operations need appropriate application-level mechanisms.

Socket addresses

#

The generic socket address structure is commonly defined as follows:

struct sockaddr
{
    unsigned short sa_family;
    char           sa_data[14];
};

For IPv4 Internet sockets, applications generally use struct sockaddr_in:

struct sockaddr_in
{
    short          sin_family;
    unsigned short sin_port;
    struct in_addr sin_addr;
    char           sin_zero[8];
};

These declarations illustrate the traditional BSD socket interface. Actual definitions come from the target system’s networking headers and should not be redeclared manually in application code.

The principal IPv4 fields are:

The generic struct sockaddr type is used by many socket functions, while struct sockaddr_in provides the IPv4-specific address representation.

Network byte ordering

#

Network protocols use big-endian byte ordering for fields such as IPv4 socket port numbers. A VxWorks target’s native byte ordering may differ, so applications should use the standard conversion functions.

C

htonl(value);  /* Host to network: 32-bit value */
htons(value);  /* Host to network: 16-bit value */

ntohl(value);  /* Network to host: 32-bit value */
ntohs(value);  /* Network to host: 16-bit value */

For example:

C

serverAddr.sin_port = htons(5001);

Without htons(), the port may be interpreted incorrectly on systems whose native byte ordering differs from network byte order.

Serializing application data

#

Correctly configuring socket addresses is only part of interoperable network programming. The application payload must also use an agreed representation when communicating between systems with different architectures or compiler conventions.

Directly transmitting a native C structure can introduce problems involving:

• Integer byte ordering.

• Differences in the size of native data types.

• Structure padding and alignment.

• Floating-point representations.

• Compiler-specific layout and packing rules.

For a simple protocol, explicitly encode each field into a documented byte sequence. For more complex interfaces, use a defined serialization format such as XDR or another suitable wire format.

The key principle is to treat the network representation as a protocol specification rather than assuming that the sender’s in-memory representation can be copied unchanged to every receiver.

Creating a socket

#

The traditional BSD socket interface uses the following form:

C

int socket(int domain, int type, int protocol);

The parameters are:

• domain: The address family, commonly AF_INET for IPv4.

• type: Typically SOCK_DGRAM for UDP or SOCK_STREAM for TCP.

• protocol: Usually 0 to select the default protocol associated with the socket type.

Example:

int sockFd;

sockFd = socket(AF_INET, SOCK_DGRAM, 0);

if (sockFd == ERROR)
{
    /* Handle socket creation failure. */
}

A successful call returns a socket descriptor. On failure, the return value is ERROR in traditional VxWorks examples. The appropriate error-reporting mechanism depends on the VxWorks release and socket library in use.

Binding a socket

#

A server commonly binds its socket to a local IP address and port so that clients can reach the service through a known endpoint.

The traditional interface is:

int bind(
    int sockFd,
    const struct sockaddr *addr,
    socklen_t addrLen
);

A server can bind to a specific local interface address or, when supported and appropriate, INADDR_ANY to accept traffic addressed to eligible local IPv4 interfaces.

Example UDP server initialization:

#include <vxWorks.h>
#include <sockLib.h>
#include <inetLib.h>
#include <netinet/in.h>
#include <string.h>

#define PORT_NUM 5001

int createUdpServer(void)
{
    int sockFd;
    struct sockaddr_in serverAddr;

    sockFd = socket(AF_INET, SOCK_DGRAM, 0);
    if (sockFd == ERROR)
    {
        return ERROR;
    }

    memset(&serverAddr, 0, sizeof(serverAddr));

    serverAddr.sin_family = AF_INET;
    serverAddr.sin_port = htons(PORT_NUM);
    serverAddr.sin_addr.s_addr = htonl(INADDR_ANY);

    if (bind(sockFd,
             (struct sockaddr *)&serverAddr,
             sizeof(serverAddr)) == ERROR)
    {
        close(sockFd);
        return ERROR;
    }

    return sockFd;
}

This function creates and binds a UDP socket. A production implementation should also include suitable logging, error reporting, configuration validation, and lifecycle management.

The specific headers and availability of functions should be checked against the target VxWorks release.

📩 UDP Socket Programming

#

UDP provides datagram-oriented communication without requiring a connection handshake before exchanging application data. Each transmitted datagram is a separate message at the transport layer.

UDP is useful for telemetry, periodic status updates, discovery protocols, and applications where the software can tolerate occasional packet loss or implement its own reliability mechanisms.

UDP socket workflow

#

UDP Socket Overview

A typical UDP client-server exchange works as follows:

1. The server creates a datagram socket.

2. The server binds the socket to a local address and port.

3. The client sends a datagram to the server’s IP address and port.

4. The server receives the datagram and can obtain the sender’s address.

5. The server optionally sends a reply to that address.

The same socket can exchange datagrams with multiple clients. UDP does not establish a persistent transport connection for each peer.

Sending data with sendto()

#

The sendto() function transmits a datagram to a specified destination address.

ssize_t sendto(
    int sockFd,
    const void *buf,
    size_t len,
    int flags,
    const struct sockaddr *destAddr,
    socklen_t destLen
);

Example:

#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <string.h>

const char message[] = "VxWorks UDP test";
struct sockaddr_in destAddr;

/* Populate destAddr with the destination IPv4 address and port. */

ssize_t sent = sendto(
    sockFd,
    message,
    sizeof(message) - 1,
    0,
    (struct sockaddr *)&destAddr,
    sizeof(destAddr)
);

if (sent == ERROR)
{
    /* Handle transmission failure. */
}

The destination address must contain the correct address family, IP address, and port in network byte order.

A successful UDP send indicates that the local stack accepted the datagram for transmission. It does not prove that the remote device received or processed it.

Receiving data with recvfrom()

#

The recvfrom() function receives a datagram and can return the sender’s address.

ssize_t recvfrom(
    int sockFd,
    void *buf,
    size_t len,
    int flags,
    struct sockaddr *srcAddr,
    socklen_t *srcLen
);

Example:

#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>

char rxBuf[512];
struct sockaddr_in clientAddr;
socklen_t clientAddrLen = sizeof(clientAddr);

ssize_t received = recvfrom(
    sockFd,
    rxBuf,
    sizeof(rxBuf),
    0,
    (struct sockaddr *)&clientAddr,
    &clientAddrLen
);

if (received == ERROR)
{
    /* Handle receive failure. */
}
else
{
    /*
     * Process exactly 'received' bytes.
     * The received data is not necessarily null-terminated.
     */
}

On a blocking socket, the call normally waits until a datagram becomes available or an error or other configured condition occurs.

Because UDP preserves datagram boundaries, the application should treat the returned byte count as the length of one received message. If a datagram exceeds the supplied buffer capacity, truncation may occur, depending on the socket API and target implementation.

UDP reliability considerations

#

UDP does not provide TCP-style retransmission, ordered delivery, or congestion control at the transport layer.

If an application needs stronger delivery guarantees, it may need to implement:

• Sequence numbers and duplicate detection.

• Acknowledgments and retransmission timers.

• Message integrity checks.

• Timeout handling and state recovery.

• Rate control appropriate to network conditions.

Not every UDP application needs all these mechanisms. They should be selected according to the system’s latency, reliability, and resource requirements.

🔄 TCP Socket Programming

#

TCP provides a reliable, ordered byte stream between two endpoints. Unlike UDP, it establishes a connection before application data is exchanged.

TCP is commonly used for command interfaces, configuration services, file transfers, remote diagnostics, and other applications where reliable transport is important.

TCP connection workflow

#

TCP Socket Overview

A TCP server typically performs the following operations:

1. Create a stream socket.

2. Bind the socket to a local address and port.

3. Call listen() to make the socket passive and configure the pending-connection queue.

4. Call accept() to obtain a new socket for each accepted connection.

5. Exchange data with the connected client.

6. Close the connected socket when communication is complete.

The listening socket remains available to accept additional clients.

TCP server initialization

#

The listen() function configures a bound stream socket to accept incoming connection requests.

int listen(int sockFd, int backlog);

The backlog parameter specifies the requested queue depth for pending connection requests. The effective value may be constrained by the networking stack or system configuration.

Accepting client connections

#

The accept() function waits for an incoming connection on a listening socket and returns a new socket descriptor representing the accepted connection.

int accept(
    int sockFd,
    struct sockaddr *clientAddr,
    socklen_t *clientAddrLen
);

The returned descriptor is used for communication with that client. The original listening socket remains available for other connection requests.

An embedded server should also consider connection limits, client timeouts, idle connections, and the resources required for concurrent clients.

TCP server design

#

A common architecture separates connection acceptance from request processing.

The following is a simplified structural example:

/* Simplified TCP server pseudocode. */

int masterFd;
struct sockaddr_in serverAddr;

masterFd = socket(AF_INET, SOCK_STREAM, 0);
if (masterFd == ERROR)
{
    return ERROR;
}

/* Initialize serverAddr with AF_INET, port, and local IP. */

if (bind(masterFd,
         (struct sockaddr *)&serverAddr,
         sizeof(serverAddr)) == ERROR)
{
    close(masterFd);
    return ERROR;
}

if (listen(masterFd, 8) == ERROR)
{
    close(masterFd);
    return ERROR;
}

for (;;)
{
    struct sockaddr_in clientAddr;
    socklen_t clientAddrLen = sizeof(clientAddr);

    int clientFd = accept(
        masterFd,
        (struct sockaddr *)&clientAddr,
        &clientAddrLen
    );

    if (clientFd == ERROR)
    {
        /* Log or handle the accept failure. */
        continue;
    }

    /*
     * Dispatch clientFd to a worker task or
     * process it in the current task.
     *
     * Define ownership of clientFd explicitly:
     * the worker that owns it should close it.
     */
}

A production implementation needs a defined worker-task entry point, task priorities and stack sizes, error handling, and a controlled shutdown mechanism.

VxWorks applications may use taskSpawn() to create worker tasks, but the server must ensure that the connected descriptor remains valid until the worker finishes processing it.

For resource-constrained systems, a fixed-size worker pool can be preferable to spawning an unlimited number of tasks.

TCP client design

#

A TCP client creates a stream socket and calls connect() using the server’s address.

int connect(
    int sockFd,
    const struct sockaddr *serverAddr,
    socklen_t addrLen
);

A simplified client sequence is:

int clientFd;
struct sockaddr_in serverAddr;

/* Initialize serverAddr with the server IP and port. */

clientFd = socket(AF_INET, SOCK_STREAM, 0);
if (clientFd == ERROR)
{
    return ERROR;
}

if (connect(clientFd,
            (struct sockaddr *)&serverAddr,
            sizeof(serverAddr)) == ERROR)
{
    close(clientFd);
    return ERROR;
}

/* Send a request and read the server's response. */

close(clientFd);

The address must contain the server’s actual IPv4 address and a port that corresponds to a listening service. Production applications should implement suitable connection timeouts and distinguish transient errors from permanent failures.

Exchanging data over TCP

#

Exchange Data

Once connected, applications can exchange data through read() and write(), or the appropriate socket-specific functions supported by the target environment.

However, TCP is a byte stream, not a message-oriented protocol.

One call to write() does not necessarily correspond to one call to read() at the receiver. Data may be split across several reads or multiple logical messages may arrive in a single read.

Applications must define message boundaries explicitly. Common approaches include:

• Fixed-length messages: Every message has a predefined size.

• Length-prefixed messages: A header specifies the payload size.

• Delimiter-terminated messages: A defined delimiter marks the end of a message.

• Structured framing: A protocol defines headers, message types, lengths, and validation rules.

Applications must also handle partial writes. A successful write() may transmit fewer bytes than requested, and a read may return fewer bytes than a complete application message requires.

For reliable request-response protocols, implement loops that track the number of bytes transferred and stop correctly when the connection closes, a timeout occurs, or an error is encountered.

Closing TCP connections

#

The close() function releases the resources associated with a socket descriptor and initiates the appropriate socket teardown behavior.

When a peer has orderly shut down its sending direction, a subsequent read on the receiving side can return zero after buffered data has been consumed. Applications should distinguish this condition from a read error.

The shutdown() function can be used to disable sending, receiving, or both directions without immediately releasing the descriptor.

For example, an application may call shutdown(sockFd, SHUT_WR) to indicate that it will send no more data while continuing to receive the peer’s response.

The precise teardown behavior can depend on pending data, linger settings, and network conditions.

⚙️ Socket Options and Nonblocking I/O

#

Socket options allow applications to tune certain behaviors for their communication requirements.

The standard setsockopt() interface is commonly used to configure these options, although the available options and supported values depend on the VxWorks version and networking stack.

Typical examples include:

• Enabling or configuring broadcast behavior for UDP.

• Adjusting send and receive buffer sizes.

• Controlling how a TCP connection handles small writes through options such as TCP_NODELAY.

• Configuring linger behavior during socket closure.

• Reusing a local address under the conditions permitted by the stack.

Address reuse does not mean that every active connection or listener can safely be duplicated. The behavior depends on the option, binding arrangement, and underlying implementation.

Blocking versus nonblocking sockets

#

A blocking socket operation may wait until data is available, a connection is established, or another completion condition occurs.

A nonblocking socket allows the task to regain control when an operation cannot complete immediately. The application must then handle the corresponding status or error and decide when to retry.

Traditional VxWorks examples often use ioctl() with FIONBIO:

int nonBlocking = 1;

/* Enable nonblocking I/O if supported by the target stack. */
if (ioctl(sockFd, FIONBIO, &nonBlocking) == ERROR)
{
    /* Handle configuration failure. */
}

Setting the value to zero typically requests blocking behavior, subject to the target implementation.

Nonblocking sockets can help prevent one task from waiting indefinitely on a single connection. However, they introduce additional state management.

Applications must handle conditions such as temporarily unavailable data, partially completed writes, and connection attempts that have not yet completed. They must also use the error-reporting conventions documented for their particular stack.

In a real-time application, socket operations should be designed so that network delays do not unexpectedly block time-critical work.

🚀 The zbuf Socket API

#

VxWorks provides a zero-copy-oriented buffer API called zbuf in relevant versions and configurations. Its purpose is to reduce the overhead associated with repeatedly copying packet data between application buffers and networking buffers.

Traditional socket operations often involve copying application data into kernel or stack-managed buffers and copying received data back into application memory. Such copying may become expensive in systems that process large packets, high packet rates, or large streams of data.

How zbuf works

#

The zbuf approach allows applications to work with networking buffers through specialized interfaces rather than always moving data through conventional copied-buffer operations.

Potential benefits include:

• Lower data-copy overhead.

• Reduced CPU usage in suitable workloads.

• Improved throughput for applications that process large amounts of network data.

• More direct integration with certain buffer-management and networking operations.

The benefits depend on the workload and stack implementation. Using a zero-copy API does not automatically improve performance if buffer management, synchronization, or other processing costs dominate the application.

Application responsibilities

#

The zbuf API introduces additional buffer-lifecycle considerations. An application must follow the ownership and release rules defined by the relevant library.

Incorrect buffer handling can cause memory leaks, premature reuse, or corruption. This is especially important in long-running embedded applications with limited memory.

The availability, exact function set, and usage conventions of zbufLib and zbufSockLib depend on the VxWorks version and product configuration. Consult the corresponding networking documentation before integrating the API.

Applications using zbuf can interoperate with conventional socket applications when they use compatible protocols and implement the same application-level wire format.

🔗 Remote Procedure Call (RPC)

#

Remote Procedure Call provides a higher-level abstraction for distributed communication. Instead of managing every request and response directly, an application invokes a procedure through a generated client stub that communicates with a server implementation.

RPC is useful when the interface consists of defined operations and structured parameters, such as querying device status, changing configuration, or requesting a remote calculation.

RPC client-server model

#

RPC Client Server Model

An RPC interaction generally involves:

1. The client application calls a local stub function.

2. The stub converts the request into a defined message representation.

3. The RPC transport sends the request to the remote server.

4. The server runtime dispatches the request to the relevant procedure.

5. The result is encoded and returned to the client.

6. The client stub decodes the response and returns the result to the application.

The RPC framework handles much of the communication machinery, but application developers still need to define interfaces, validate data, handle failures, and manage service lifecycles.

rpcgen and interface generation

#

The traditional Sun RPC tool rpcgen generates source files from a protocol specification describing remote procedures and their parameters.

Depending on the interface and options used, the generated code may include:

• Client stubs.

• Server dispatch and stub code.

• XDR serialization and deserialization routines.

• Header declarations shared by the client and server.

The use of XDR helps standardize data representation across systems with different native byte ordering and data layouts.

For simple standard parameter types, some serialization code may be generated directly or may not require separate custom routines. More complex structures generally need appropriate XDR definitions.

XDR and portable data representation

#

External Data Representation (XDR) defines a standard way to represent data independently of the host computer’s memory layout.

This helps address common interoperability issues, including:

• Integer byte ordering.

• Structure layout differences.

• Data alignment.

• Standardized representations of supported data types.

A well-defined RPC interface can therefore help prevent the subtle compatibility problems associated with sending raw C structures across a network.

Initializing RPC support

#

Older VxWorks networking environments may provide RPC facilities requiring per-task initialization. For example, legacy documentation may refer to an initialization routine such as:

STATUS rpcTaskInit(void);

This declaration should not be assumed to be available in every VxWorks release. RPC library availability, initialization procedures, and source locations vary between versions and distributions.

Before adopting a legacy RPC implementation, verify the relevant documentation and consider whether its security, maintenance, and interoperability characteristics satisfy the project’s requirements.

RPC also requires suitable error handling for transport failures, unavailable services, timeouts, and unsuccessful remote operations. A remote procedure call should not be assumed to execute successfully merely because the client invoked the local stub.

🛠️ Practical Design and Troubleshooting Guidelines

#

Correct use of socket APIs is only one part of building a reliable embedded network service. Addressing, buffer management, task scheduling, and error handling are equally important.

Validate addresses and byte ordering

#

Always initialize socket address structures before populating their fields. Use htons() for port values and the relevant address conversion routines when translating textual IPv4 addresses.

If a client cannot reach a server, verify that both endpoints agree on the destination address, port, transport protocol, and network interface.

Define the application protocol

#

For TCP, specify how the receiver identifies complete messages. For UDP, define maximum message sizes and determine how the application handles lost, duplicated, or out-of-order datagrams.

If clients and servers run on different processor architectures, serialize multibyte values explicitly rather than transmitting compiler-dependent C structures directly.

Handle partial transfers and errors

#

TCP applications should implement loops for sending and receiving complete framed messages. They should also handle connection closure, timeout conditions, and transient errors.

UDP applications should validate received datagram lengths and avoid interpreting untrusted payload data beyond the number of bytes actually received.

Protect real-time task execution

#

Network operations can introduce nondeterministic delays. Avoid placing indefinitely blocking socket operations inside time-critical control tasks.

Depending on the application, a design may use dedicated network tasks, bounded queues, nonblocking sockets, timeouts, or a worker pool.

Task priorities and CPU utilization also matter. A network service should not consume so much execution time that it interferes with higher-priority real-time functions.

Manage resources deliberately

#

Embedded systems often have strict memory and descriptor limits. Close sockets when they are no longer needed, release buffers according to their ownership rules, and enforce limits on concurrent clients.

For servers, consider what happens if a client disconnects during a request or never completes a message. Idle connection limits and bounded resource allocation help prevent abandoned clients from exhausting system resources.

📚 TCP, UDP, zbuf, and RPC: Choosing the Right Interface

#

Different communication mechanisms solve different problems. Selecting the right one requires balancing transport behavior, implementation complexity, throughput, portability, and real-time constraints.

TCP and UDP are transport protocols, while sockets are a programming interface to those protocols. zbuf provides specialized buffer-management facilities, and RPC is a higher-level communication framework.

These mechanisms are not always mutually exclusive. An RPC implementation may use a transport underneath, while applications may choose conventional sockets or specialized buffer interfaces for different paths through the same system.

Final summary

#

Reliable VxWorks network programming begins with a clear understanding of the TCP/IP model, socket addressing, and network byte ordering.

For straightforward communication, Berkeley sockets provide a familiar interface to TCP and UDP. TCP is suitable for reliable byte-stream applications, while UDP is appropriate when datagram-oriented communication and application-specific delivery behavior are preferred.

More specialized applications can benefit from zbuf buffer handling or RPC-based service interfaces, provided those facilities are supported by the selected VxWorks environment.

The most robust embedded network designs combine correct API usage with explicit message framing, disciplined buffer and socket ownership, comprehensive error handling, and a clear separation between network processing and time-critical tasks. These fundamentals form a practical foundation for building maintainable and predictable distributed applications on VxWorks.