epicsStdio.h

Standardize the behavior of stdio across EPICS targets.

The epicsStdio.h header includes the operating system’s stdio.h header and if used should replace it.

epicsSnprintf() and epicsVsnprintf() have the same semantics as the C99 functions snprintf() and vsnprintf(), but correct the behavior of the implementations on some operating systems.

The routines epicsGetStdin(), epicsGetStdout(), epicsGetStderr(), epicsStdoutPrintf(), epicsStdoutPuts(), and epicsStdoutPutchar() are not normally named directly in user code. They are provided for use by various macros which redefine several standard C identifiers. This is done so that any I/O through these standard streams can be redirected, usually to or from a file. The primary use of this facility is for iocsh() and any commands called from it, allowing redirection of the standard input and/or output streams while running those commands. In order for this redirection to work, all modules involved in such I/O must include epicsStdio.h instead of the system header stdio.h. The redirections are:

stdin becomes epicsGetStdin()
stdout becomes epicsGetStdout()
stderr becomes epicsGetStderr()
printf becomes epicsStdoutPrintf()
puts becomes epicsStdoutPuts()
putchar becomes epicsStdoutPutchar()
vprintf becomes epicsStdoutVPrintf()

The epicsSetThreadStdin(), epicsSetThreadStdout() and epicsSetThreadStderr() routines allow the standard file streams to be redirected on a per thread basis, e.g. calling epicsThreadStdout() will affect only the thread which calls it. To cancel a stream redirection, pass a NULL argument in another call to the same redirection routine that was used to set it.

Since: 3.15.6 define epicsStdioStdPrintfEtc to opt out of redefinition for printf, vprintf, puts, and putchar.
Since: 3.15.0 define epicsStdioStdStreams to opt out of redefinition of stdin, stdout, and stderr.

Note

Define epicsStdioStdStreams and/or epicsStdioStdPrintfEtc to opt out of the redirection described below.

Defines

stdin

stdout

stderr

printf

vprintf

puts

putchar

Enums

enum TF_RETURN

Values:

enumerator TF_OK

enumerator TF_ERROR

Functions

int epicsSnprintf(char *str, size_t size, const char *format, ...)

Wrapper around OS snprintf()

This is provided because some architectures do not implement these functions, while others implement them incorrectly. Standardized as a C99 function, snprintf() acts like sprintf() except that the size argument gives the maximum number of characters (including the trailing zero byte) that may be placed in str.

On some operating systems though the implementation of this function does not always return the correct value. If the OS implementation does not correctly return the number of characters that would have been written when the output gets truncated, it is not worth trying to fix this as long as they return size-1 instead; the resulting string must always be correctly null terminated.

In some scenarios the epicsSnprintf() implementation may not provide the correct C99 semantics for the return value when size is given as zero. On these systems epicsSnprintf() can return an error (a value less than zero) when a buffer length of zero is passed in, so callers should not use that technique to calculate the length of the buffer required.

Parameters:

str – Output buffer. Must be non-NULL.
size – Capacity of output buffer, including space for nil. Must be a positive value.
format – Format string. Must be non-NULL.

Returns:

Non-negative value on success (see below).

Post:

On success, at least a nil charactor has been written to the output buffer. On failure, the output buffer state is not specified.

int epicsVsnprintf(char *str, size_t size, const char *format, va_list ap)

vararg version of epicsSnprintf()

Wrapper around OS vsnprintf().