Printf-style formatted output to file descriptors. More...

Functions
int	fdprintf (int fd, const char *format,...)
	Print formatted output to a file descriptor.
int	fdiprintf (int fd, const char *format,...)
	Print formatted output to a file descriptor (integer-only, no float).
int	vfdprintf (int fd, const char *format, va_list args)
	Print formatted output to a file descriptor using va_list.
int	vfdiprintf (int fd, const char *format, va_list args)
	Print formatted output to a file descriptor using va_list (integer-only).

Detailed Description

Printf-style formatted output to file descriptors.

#include< fdprintf.h>

The fdprintf family of functions extends the familiar printf() functionality to work with any file descriptor in the NetBurner system. This enables formatted output to:

Serial ports (UART)
TCP/IP network connections
UDP sockets
Custom file descriptors
Any device that implements the file descriptor interface

Overview

Unlike printf() which outputs to stdout (typically the debug serial port), fdprintf() allows you to direct formatted output to any open file descriptor. This is essential for network protocols, multi-port communications, and custom output devices.

Function Variants

Four variants are provided to suit different needs:

Function	Float Support	Argument Type	Use Case
fdprintf()	Yes	Variable args	General purpose with float
fdiprintf()	No	Variable args	Integer-only (smaller code)
vfdprintf()	Yes	va_list	Wrapper functions with float
vfdiprintf()	No	va_list	Wrapper functions, integer-only

Example Usage

Serial Port Output

#include <fdprintf.h>
#include <serial.h>
 
void sendSerialData() {
    int serialFd = SimpleOpenSerial(0, 115200);
    
    fdprintf(serialFd, "Temperature: %.2f C\r\n", 23.45);
    fdprintf(serialFd, "Status: %s\r\n", "OK");
    
    close(serialFd);
}

Network Socket Output

#include <fdprintf.h>
#include <tcp.h>
 
void sendToClient(int clientFd) {
    fdprintf(clientFd, "HTTP/1.1 200 OK\r\n");
    fdprintf(clientFd, "Content-Type: text/html\r\n\r\n");
    fdprintf(clientFd, "<html><body>\r\n");
    fdprintf(clientFd, "<h1>Device Status</h1>\r\n");
    fdprintf(clientFd, "<p>Uptime: %lu seconds</p>\r\n", Secs);
    fdprintf(clientFd, "</body></html>\r\n");
}

Creating Wrapper Functions

#include <fdprintf.h>
#include <stdarg.h>
 
// Custom logging function that adds timestamps
void logToSerial(const char *format, ...) {
    static int logFd = -1;
    
    if (logFd < 0) {
        logFd = SimpleOpenSerial(1, 115200);
    }
    
    // Print timestamp
    fdprintf(logFd, "[%lu] ", Secs);
    
    // Print user message using va_list
    va_list args;
    va_start(args, format);
    vfdprintf(logFd, format, args);
    va_end(args);
}
 
// Usage
logToSerial("Sensor reading: %d\n", sensorValue);

Integer-Only for Code Size

#include <fdprintf.h>
 
// Use fdiprintf when you don't need floating point
// This saves significant code space
void sendIntegerStatus(int fd) {
    fdiprintf(fd, "Counter: %d\r\n", counter);
    fdiprintf(fd, "Error Code: 0x%08X\r\n", errorCode);
    fdiprintf(fd, "Status: %s\r\n", statusString);
}

Format Specifiers

fdprintf() supports standard C printf format specifiers:

d, i - Signed decimal integer
u - Unsigned decimal integer
x, X - Hexadecimal
o - Octal
c - Character
s - String
p - Pointer
f, e, g - Floating point (fdprintf/vfdprintf only)
%% - Literal %

Width, precision, and flags are supported:

%5d - Minimum width
%05d - Zero-padded width
%.2f - Precision
%-10s - Left-aligned
%+d - Force sign

Performance Considerations

Code Size: fdiprintf() is ~10-15KB smaller than fdprintf() due to no float support
Speed: Integer formatting is faster than floating point
Buffering: Consider buffering for high-frequency output
Network: fdprintf() to network sockets may block if buffer is full

Best Practices

Error Checking: Always check file descriptor validity before use
Return Value: Check return value for write errors
Buffer Size: Be aware of output buffer limits on network sockets
Float Support: Use fdiprintf() when floating point is not needed
Line Endings: Use \r\n for network protocols and serial terminals

Important Notes

Note: The fdprintf() family does not append a newline automatically. You must include \n or \r\n in your format string if desired.; Output to network sockets may block if the socket send buffer is full. Consider using non-blocking I/O or checking buffer space for critical applications.; File descriptors must be properly opened before use and closed when done.

Warning: Floating point formatting (fdprintf/vfdprintf) increases code size significantly. Use fdiprintf or vfdiprintf when float support is not required.; Large format strings or many arguments can overflow stack space. Keep format operations reasonably sized.

Example Code

Complete examples are available in the NetBurner SDK:

\nburn\examples\Filedescriptor - File descriptor usage examples
Examples include custom file descriptor creation and usage

See also: printf() Standard printf to stdout; iprintf() Integer-only printf to stdout; snprintf() Format to string buffer; writeall() Write raw data to file descriptor

Function Documentation

◆ fdiprintf()

int fdiprintf	(	int	fd,
		const char *	format,
			... )

#include <fdprintf.h>

Print formatted output to a file descriptor (integer-only, no float).

Similar to fdprintf() but without floating point support. This significantly reduces code size (~10-15KB smaller) and is faster for integer-only formatting. Use this when you only need to format integers, strings, and other non-float types.

Parameters

fd	File descriptor to write to. Must be a valid, open file descriptor such as: Serial port (from SimpleOpenSerial()) TCP socket (from accept() or connect()) UDP socket (from socket()) Custom file descriptor
format	Format string using standard printf syntax. Supports all specifiers EXCEPT floating point (f, e, g are not supported): Integer formats: d, i, u, x, X, o String format: s Character format: c Pointer format: p Width and precision modifiers
...	Variable arguments corresponding to format specifiers in the format string

Returns: Number of bytes written to the file descriptor, or negative value on error

Return values

>0	Number of bytes successfully written
<0	Error occurred during write operation

Precondition: fd must be a valid, open file descriptor; format must not be NULL; format must not contain floating point specifiers (f, e, g)

Postcondition: Data is written to the file descriptor's output buffer

Note: This function does NOT support floating point formatting. Attempting to use f, e, or g will produce undefined results.; No newline is automatically appended. Include \n or \r\n in the format string if line ending is desired.

Warning: Using floating point specifiers (f, e, g) will cause undefined behavior. Use fdprintf() if float formatting is needed.

Example: Basic Integer Output: int fd = SimpleOpenSerial(0, 115200);

if (fd >= 0) {

fdiprintf(fd, "Counter: %d\r\n", counter);

fdiprintf(fd, "Status: 0x%08X\r\n", status);

close(fd);

}

fdiprintf
int fdiprintf(int fd, const char *format,...)
Print formatted output to a file descriptor (integer-only, no float).

Example: Network Status Messages: void sendStatus(int clientFd) {

fdiprintf(clientFd, "Device ID: %d\r\n", deviceId);

fdiprintf(clientFd, "Uptime: %lu seconds\r\n", Secs);

fdiprintf(clientFd, "Memory Free: %d bytes\r\n", OSFreeMemory());

}

Example: Code Size Optimization: // Instead of this (adds 15KB):

fdprintf(fd, "Value: %d\n", value);

// Use this (saves 15KB if no other float formatting):

fdiprintf(fd, "Value: %d\n", value);

See also: fdprintf() Full version with floating point support; vfdiprintf() va_list version for wrapper functions; iprintf() Integer-only printf to stdout

◆ fdprintf()

int fdprintf	(	int	fd,
		const char *	format,
			... )

#include <fdprintf.h>

Print formatted output to a file descriptor.

Outputs formatted text to the specified file descriptor using the same format syntax as standard printf(). Supports all standard format specifiers including floating point.

Parameters

fd	File descriptor to write to. Must be a valid, open file descriptor such as: Serial port (from SimpleOpenSerial()) TCP socket (from accept() or connect()) UDP socket (from socket()) Custom file descriptor
format	Format string using standard printf syntax. Supports: All standard format specifiers (d, s, f, x, etc.) Width and precision modifiers (%-10s, %.2f, %05d) All standard flags (+, -, 0, space, #)
...	Variable arguments corresponding to format specifiers in the format string

Returns: Number of bytes written to the file descriptor, or negative value on error

Return values

>0	Number of bytes successfully written
<0	Error occurred during write operation

Precondition: fd must be a valid, open file descriptor; format must not be NULL

Postcondition: Data is written to the file descriptor's output buffer; On network sockets, data may be queued for transmission

Note: This function includes floating point support which adds ~10-15KB to code size. Use fdiprintf() if floating point is not needed.; No newline is automatically appended. Include \n or \r\n in the format string if line ending is desired.

Warning: May block if writing to a network socket with a full send buffer. Consider non-blocking I/O for time-critical applications.; Very large format operations may overflow stack space. Keep output operations reasonably sized.

Example: Basic Usage: int fd = SimpleOpenSerial(0, 115200);

if (fd >= 0) {

fdprintf(fd, "Temperature: %.2f C\r\n", 23.45);

close(fd);

}

Example: Network Protocol: void sendHTTPResponse(int clientFd, int statusCode) {

fdprintf(clientFd, "HTTP/1.1 %d OK\r\n", statusCode);

fdprintf(clientFd, "Content-Length: %d\r\n", contentLen);

fdprintf(clientFd, "\r\n");

}

Example: Error Checking: int bytesWritten = fdprintf(fd, "Status: %d\n", status);

if (bytesWritten < 0) {

iprintf("Error writing to file descriptor\n");

}

See also: fdiprintf() Integer-only version (smaller code size); vfdprintf() va_list version for wrapper functions; printf() Standard output version

◆ vfdiprintf()

int vfdiprintf	(	int	fd,
		const char *	format,
		va_list	args )

#include <fdprintf.h>

Print formatted output to a file descriptor using va_list (integer-only).

Variant of fdiprintf() that accepts a va_list argument instead of variable arguments. This is used for creating wrapper functions that need to forward variable arguments. Does NOT support floating point, resulting in smaller code size.

Parameters

fd	File descriptor to write to. Must be a valid, open file descriptor
format	Format string using standard printf syntax. Supports all specifiers EXCEPT floating point (f, e, g are not supported): Integer formats: d, i, u, x, X, o String format: s Character format: c Pointer format: p
args	Variable argument list (va_list) containing the arguments specified by the format string. Must be initialized with va_start() and cleaned up with va_end()

Returns: Number of bytes written to the file descriptor, or negative value on error

Return values

>0	Number of bytes successfully written
<0	Error occurred during write operation

Precondition: fd must be a valid, open file descriptor; format must not be NULL; format must not contain floating point specifiers (f, e, g); args must be properly initialized with va_start()

Postcondition: Data is written to the file descriptor's output buffer; args parameter is consumed and should not be reused

Note: This function does NOT support floating point formatting. Use vfdprintf() if float support is needed.; The caller is responsible for calling va_start() before calling this function and va_end() after the call.; This function is ~10-15KB smaller than vfdprintf() due to lack of floating point support.

Warning: Using floating point specifiers (f, e, g) will cause undefined behavior. Use vfdprintf() if float formatting is needed.

Example: Integer-Only Logging Wrapper: #include <fdprintf.h>

#include <stdarg.h>

// Memory-efficient logging (no float support)

void quickLog(int fd, const char *format, ...) {

va_list args;

va_start(args, format);

vfdiprintf(fd, format, args);

va_end(args);

}

// Usage - only integers and strings

quickLog(logFd, "Counter: %d, Status: %s\n", count, status);

vfdiprintf
int vfdiprintf(int fd, const char *format, va_list args)
Print formatted output to a file descriptor using va_list (integer-only).

Example: Diagnostic Output Wrapper: void diagPrint(const char *format, ...) {

static int diagFd = -1;

if (diagFd < 0) {

diagFd = SimpleOpenSerial(2, 115200);

}

if (diagFd >= 0) {

va_list args;

va_start(args, format);

vfdiprintf(diagFd, format, args);

va_end(args);

}

}

// Usage

diagPrint("Error Code: 0x%08X\n", errorCode);

diagPrint("Free Memory: %d bytes\n", OSFreeMemory());

Example: Protocol Wrapper: // Modbus protocol wrapper (integer-only)

void modbusResponse(int fd, uint8_t funcCode, ...) {

fdiprintf(fd, ":%02X", funcCode);

va_list args;

va_start(args, funcCode);

// Additional data fields

int dataCount = va_arg(args, int);

for (int i = 0; i < dataCount; i++) {

int value = va_arg(args, int);

fdiprintf(fd, "%04X", value);

}

va_end(args);

fdiprintf(fd, "\r\n");

}

See also: fdiprintf() Direct variable argument version; vfdprintf() Full version with floating point support; va_start() Initialize va_list; va_end() Clean up va_list

◆ vfdprintf()

int vfdprintf	(	int	fd,
		const char *	format,
		va_list	args )

#include <fdprintf.h>

Print formatted output to a file descriptor using va_list.

Variant of fdprintf() that accepts a va_list argument instead of variable arguments. This is used for creating wrapper functions that need to forward variable arguments. Includes full floating point support.

Parameters

fd	File descriptor to write to. Must be a valid, open file descriptor
format	Format string using standard printf syntax. Supports all standard format specifiers including floating point
args	Variable argument list (va_list) containing the arguments specified by the format string. Must be initialized with va_start() and cleaned up with va_end()

Returns: Number of bytes written to the file descriptor, or negative value on error

Return values

>0	Number of bytes successfully written
<0	Error occurred during write operation

Precondition: fd must be a valid, open file descriptor; format must not be NULL; args must be properly initialized with va_start()

Postcondition: Data is written to the file descriptor's output buffer; args parameter is consumed and should not be reused

Note: This function is primarily used for creating wrapper functions. Direct application code should typically use fdprintf() instead.; The caller is responsible for calling va_start() before calling this function and va_end() after the call.; This function includes floating point support. Use vfdiprintf() for integer-only formatting to save code space.

Example: Creating a Logging Wrapper: #include <fdprintf.h>

#include <stdarg.h>

// Custom logging function with automatic timestamp

void logMessage(int fd, const char *format, ...) {

// Add timestamp prefix

fdprintf(fd, "[%lu] ", Secs);

// Forward variable arguments to vfdprintf

va_list args;

va_start(args, format);

vfdprintf(fd, format, args);

va_end(args);

}

// Usage

int logFd = SimpleOpenSerial(1, 115200);

logMessage(logFd, "Temperature: %.2f C\n", temp);

logMessage(logFd, "Status: %s\n", statusStr);

Example: Multi-Destination Output: void sendToMultiple(const char *format, ...) {

va_list args;

// Send to serial port

va_start(args, format);

vfdprintf(serialFd, format, args);

va_end(args);

// Send to network client

va_start(args, format);

vfdprintf(networkFd, format, args);

va_end(args);

}

Example: Buffered Output Wrapper: static char outputBuffer[512];

void bufferedOutput(int fd, const char *format, ...) {

// Format to buffer first

va_list args;

va_start(args, format);

int len = vsnprintf(outputBuffer, sizeof(outputBuffer), format, args);

va_end(args);

// Write buffer to fd

if (len > 0) {

writeall(fd, outputBuffer, len);

}

}

writeall
int writeall(int fd, const char *buf, int nbytes=0)
Write the specified number of bytes to a file descriptor. Will block until all bytes are sent,...

See also: fdprintf() Direct variable argument version; vfdiprintf() Integer-only va_list version; va_start() Initialize va_list; va_end() Clean up va_list