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

epicsSnprintf() is meant to have the same semantics as the C99 function 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 terminated with a zero byte.

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.

Returns:

The number of characters (not counting the terminating zero byte) that would be written to str if it was large enough to hold them all; the output has been truncated if the return value is size or more.

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

epicsVsnprintf() is meant to have the same semantics as the C99 function vsnprintf()

This is provided because some architectures do not implement these functions, while others implement them incorrectly. Standardized as a C99 function, vsnprintf() acts like vsprintf() 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 terminated with a zero byte.

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.

Returns:

The number of characters (not counting the terminating zero byte) that would be written to str if it was large enough to hold them all; the output has been truncated if the return value is size or more.

enum TF_RETURN truncateFile(const char *pFileName, unsigned long size)

Truncate a file to a specified size.

Note

The BSD function truncate() was not available on all targets

Parameters:
  • pFileName – Name (and optionally path) of file

  • size – The new file size (if files is currently larger)

Returns:

TF_OK if the file is less that size bytes or if it was successfully truncated; TF_ERROR if the file could not be truncated

FILE *epicsGetStdin(void)
FILE *epicsGetStdout(void)
FILE *epicsGetStderr(void)
FILE *epicsGetThreadStdin(void)
FILE *epicsGetThreadStdout(void)
FILE *epicsGetThreadStderr(void)
void epicsSetThreadStdin(FILE*)
void epicsSetThreadStdout(FILE*)
void epicsSetThreadStderr(FILE*)
int epicsStdoutPrintf(const char *pformat, ...)
int epicsStdoutVPrintf(const char *pformat, va_list ap)
int epicsStdoutPuts(const char *str)
int epicsStdoutPutchar(int c)
namespace std

STL namespace.