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 forprintf
,vprintf
,puts
, andputchar
.- Since
3.15.0 define
epicsStdioStdStreams
to opt out of redefinition ofstdin
,stdout
, andstderr
.
Note
Define epicsStdioStdStreams
and/or epicsStdioStdPrintfEtc
to opt out of the redirection described below.
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 instr
.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 issize
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 instr
.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 issize
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.