epicsStdio.h File Reference

Standardize the behavior of stdio across EPICS targets. More...

#include <stdio.h>
#include <stdarg.h>
#include "libComAPI.h"
#include "compilerDependencies.h"
#include "epicsTempFile.h"

Include dependency graph for epicsStdio.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	stdin   epicsGetStdin()
#define	stdout   epicsGetStdout()
#define	stderr   epicsGetStderr()
#define	printf   epicsStdoutPrintf
#define	puts   epicsStdoutPuts
#define	putchar   epicsStdoutPutchar

Enumerations
enum	TF_RETURN { TF_OK =0, TF_ERROR =1 }

Functions
LIBCOM_API int epicsStdCall	epicsSnprintf (char *str, size_t size, const char *format,...) EPICS_PRINTF_STYLE(3
	epicsSnprintf() is meant to have the same semantics as the C99 function snprintf() More...
LIBCOM_API int epicsStdCall LIBCOM_API int epicsStdCall	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() More...
LIBCOM_API enum TF_RETURN	truncateFile (const char *pFileName, unsigned long size)
	Truncate a file to a specified size. More...
LIBCOM_API FILE *epicsStdCall	epicsGetStdin (void)
LIBCOM_API FILE *epicsStdCall	epicsGetStdout (void)
LIBCOM_API FILE *epicsStdCall	epicsGetStderr (void)
LIBCOM_API FILE *epicsStdCall	epicsGetThreadStdin (void)
LIBCOM_API FILE *epicsStdCall	epicsGetThreadStdout (void)
LIBCOM_API FILE *epicsStdCall	epicsGetThreadStderr (void)
LIBCOM_API void epicsStdCall	epicsSetThreadStdin (FILE *)
LIBCOM_API void epicsStdCall	epicsSetThreadStdout (FILE *)
LIBCOM_API void epicsStdCall	epicsSetThreadStderr (FILE *)
LIBCOM_API int epicsStdCall	epicsStdoutPrintf (const char *pformat,...) EPICS_PRINTF_STYLE(1
LIBCOM_API int epicsStdCall LIBCOM_API int epicsStdCall	epicsStdoutPuts (const char *str)
LIBCOM_API int epicsStdCall	epicsStdoutPutchar (int c)

Detailed Description

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()

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.

Definition in file epicsStdio.h.

Function Documentation

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

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.

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

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.

LIBCOM_API enum TF_RETURN truncateFile	(	const char *	pFileName,
		unsigned long	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