this class provides a simple C++ encapsulation layer for stdio FILE pointers. More...

Public Member Functions
	OFFile ()
	default constructor, creates an object that is not associated with any file.

	OFFile (FILE *f)
	create object for given stdio FILE More...

	~OFFile ()
	destructor. Closes file if still open.

OFBool	fopen (const char filename, const char modes)
	opens the file whose name is the string pointed to by path and associates a stream with it. More...

OFBool	wfopen (const wchar_t filename, const wchar_t modes)
	opens the file whose name is the wide character string pointed to by path and associates a stream with it. More...

OFBool	fopen (const OFFilename &filename, const char *modes)
	opens the file whose name is a conventional or wide character string pointed to by path and associates. More...

OFBool	fdopen (int fd, const char *modes)
	associates a stream with the existing file descriptor 'fd'. More...

OFBool	popen (const char command, const char modes)
	opens a process by creating a pipe, forking, and invoking the shell. More...

OFBool	freopen (const char filename, const char modes)
	opens the file whose name is the string pointed to by path and associates the stream pointed maintained by this object with it. More...

OFBool	tmpfile ()
	generates a unique temporary filename. More...

int	fclose ()
	dissociates the named stream from its underlying file or set of functions. More...

int	pclose ()
	waits for the associated process (created with popen) to terminate and returns the exit status of the command as returned by wait4. More...

size_t	fwrite (const void *ptr, size_t size, size_t n)
	writes n elements of data, each size bytes long, to the stream, obtaining them from the location given by ptr. More...

size_t	fread (void *ptr, size_t size, size_t n)
	reads n elements of data, each size bytes long, from the stream, storing them at the location given by ptr. More...

int	fflush ()
	forces a write of all user-space buffered data for the given output or update stream via the stream's underlying write function. More...

int	fgetc ()
	reads the next character from stream and returns it as an unsigned char cast to an int, or EOF on end of file or error. More...

void	setlinebuf ()
	The three types of buffering available are unbuffered, block buffered, and line buffered. More...

void	rewind ()
	sets the file position indicator for the stream pointed to by stream to the beginning of the file. More...

void	clearerr ()
	clears the end-of-file and error indicators for the stream

int	eof () const
	tests the end-of-file indicator for the stream, returning non-zero if it is set. More...

int	error ()
	tests the error indicator for the stream, returning non-zero if it is set. More...

int	fileNo ()
	returns the low-level file descriptor associated with the stream. More...

void	setbuf (char *buf)
	The three types of buffering available are unbuffered, block buffered, and line buffered. More...

int	setvbuf (char *buf, int modes, size_t n)
	The three types of buffering available are unbuffered, block buffered, and line buffered. More...

void	setbuffer (char *buf, size_t size)
	The three types of buffering available are unbuffered, block buffered, and line buffered. More...

int	fputc (int c)
	writes the character c, cast to an unsigned char, to stream. More...

char *	fgets (char *s, int n)
	reads in at most one less than n characters from stream and stores them into the buffer pointed to by s. More...

int	fputs (const char *s)
	writes the string s to stream, without its trailing '\0'. More...

int	ungetc (int c)
	pushes c back to stream, cast to unsigned char, where it is available for subsequent read operations. More...

int	fseek (offile_off_t off, int whence)
	sets the file position indicator for the stream pointed to by stream. More...

offile_off_t	ftell ()
	obtains the current value of the file position indicator for the stream pointed to by the stream. More...

int	fgetpos (offile_fpos_t *pos)
	alternate interface equivalent to ftell, storing the current value of the file offset into the object referenced by pos. More...

int	fsetpos (offile_fpos_t *pos)
	alternate interface equivalent to fseek (with whence set to SEEK_SET), setting the current value of the file offset from the object referenced by pos. More...

int	fprintf (const char *format,...)
	print formatted string into stream, see printf(3) More...

int	vfprintf (const char *format, va_list arg)
	print formatted string into stream, see printf(3) More...

FILE *	file ()
	return FILE pointer managed by this object. More...

OFBool	open () const
	return true if this object is currently associated with a stream, false otherwise More...

offile_errno_t	getLastError () const
	return last error code for this stream More...

void	getLastErrorString (OFString &s) const
	return string describing last error code for this stream More...

int	fwide (int mode)
	When mode is zero, the fwide function determines the current orientation of stream. More...

wint_t	fgetwc ()
	reads a wide character from stream and returns it. More...

wint_t	fputwc (wchar_t wc)
	writes the wide character wc to stream. More...

wint_t	ungetwc (wint_t wc)
	pushes back a wide character onto stream and returns it. More...

int	fwprintf (const wchar_t *format,...)
	print formatted wide string into stream, see wprintf(3) More...

int	vfwprintf (const wchar_t *format, va_list arg)
	print formatted wide string into stream, see printf(3) More...

Private Member Functions
void	storeLastError ()
	store last error code. For now we simply store the content of errno.

Private Attributes
FILE *	file_
	the file maintained by this object

OFBool	popened_
	a flag indicating whether or not this object was created with popen().

offile_errno_t	lasterror_
	the last error code for operations of this stream

Detailed Description

this class provides a simple C++ encapsulation layer for stdio FILE pointers.

All stdio functions on files are directly mapped into member functions. The handling of large files (64 bit file systems) is transparent. Instead of type off_t, fseek() and ftell() use offile_off_t which is a 64 bit type if available on the underlying platform. Similarly, getpos() and setpos() use type offile_fpos_t, which is defined appropriately. This class provides both fclose() and pclose(), but these are equivalent - the code always closes pipes with pclose() and files with fclose(). Finally, an abstraction for errno is provided. Error codes should always be retrieves using methods getLastError() and getLastErrorString() which on Unix platforms are based on errno and strerror/strerror_r, but may be based on other mechanisms on platforms where errno does not exist.

Constructor & Destructor Documentation

◆ OFFile()

OFFile::OFFile ( FILE * f )

inline

create object for given stdio FILE

Parameters

f	stdio FILE

Member Function Documentation

◆ eof()

int OFFile::eof ( ) const

inline

tests the end-of-file indicator for the stream, returning non-zero if it is set.

The end-of-file indicator can only be cleared by the function clearerr. This method is called eof, not feof, because feof() is a macro on some systems and, therefore, cannot be used as a method name.

Returns: non-zero if EOF, zero otherwise

◆ error()

int OFFile::error ( )

inline

tests the error indicator for the stream, returning non-zero if it is set.

This method is named error, not ferror, because ferror() is a macro on some systems and, therefore, cannot be used as a method name. The error indicator can only be reset by the clearerr function.

Returns: non-zero if error flag is set, zero otherwise

◆ fclose()

int OFFile::fclose ( )

dissociates the named stream from its underlying file or set of functions.

If the stream was being used for output, any buffered data is written first, using fflush. Independent of the return value of this method, any further access (including another call to fclose()) to the stream maintained by this object results in undefined behaviour.

Returns: 0 upon success, EOF otherwise, in which case the error code is set.

◆ fdopen()

OFBool OFFile::fdopen	(	int	fd,
		const char *	modes
	)

inline

associates a stream with the existing file descriptor 'fd'.

The mode of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") must be compatible with the mode of the file descriptor. The file position indicator of the new stream is set to that belonging to 'fd', and the error and end-of-file indicators are cleared. Modes "w" or "w+" do not cause truncation of the file. The file descriptor is not dup'ed, and will be closed when the stream created by fdopen is closed. The result of applying fdopen to a shared memory object is undefined.

Parameters

fd	file descriptor
modes	"r", "w" or "a" with possible modifiers "+", "b"

Returns: true if stream was successfully created, false otherwise, in which case the error code is set.

◆ fflush()

int OFFile::fflush ( )

inline

forces a write of all user-space buffered data for the given output or update stream via the stream's underlying write function.

The open status of the stream is unaffected.

Returns: 0 upon success, EOF otherwise, in which case the error code is set.

◆ fgetc()

int OFFile::fgetc ( )

inline

reads the next character from stream and returns it as an unsigned char cast to an int, or EOF on end of file or error.

Returns: next character from stream or EOF

◆ fgetpos()

int OFFile::fgetpos ( offile_fpos_t * pos )

inline

alternate interface equivalent to ftell, storing the current value of the file offset into the object referenced by pos.

On some non-UNIX systems an fpos_t object may be a complex object and these routines may be the only way to portably reposition a text stream.

Parameters

pos	pointer to offile_fpos_t structure

Returns: 0 upon success, -1 otherwise in which case the error code is set.

◆ fgets()

char* OFFile::fgets	(	char *	s,
		int	n
	)

inline

reads in at most one less than n characters from stream and stores them into the buffer pointed to by s.

Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer. A '\0' is stored after the last character in the buffer.

Parameters

s	pointer to buffer of size n
n	buffer size

Returns: pointer to string

◆ fgetwc()

wint_t OFFile::fgetwc ( )

inline

reads a wide character from stream and returns it.

If the end of stream is reached, or if ferror(stream) becomes true, it returns WEOF. If a wide character conversion error occurs, it sets the error code to EILSEQ and returns WEOF.

Returns: next character from stream or WEOF

◆ file()

FILE* OFFile::file ( )

inline

return FILE pointer managed by this object.

This allows the user to call some stdio functions that are not encapsulated in this class (but possibly should be).

Returns: pointer to FILE structure managed by this object

◆ fileNo()

int OFFile::fileNo ( )

inline

returns the low-level file descriptor associated with the stream.

The spelling of this member function is different from stdio fileno() because on some systems (such as MinGW) fileno() is a macro and, therefore, cannot be used as a method name.

Returns: low-level file descriptor associated with stream

◆ fopen() [1/2]

OFBool OFFile::fopen	(	const char *	filename,
		const char *	modes
	)

inline

opens the file whose name is the string pointed to by path and associates a stream with it.

Parameters

filename	path to file
modes	"r", "w" or "a" with possible modifiers "+", "b"

Returns: true if stream was successfully created, false otherwise, in which case the error code is set.

◆ fopen() [2/2]

OFBool OFFile::fopen	(	const OFFilename &	filename,
		const char *	modes
	)

inline

opens the file whose name is a conventional or wide character string pointed to by path and associates.

The wide character support is currently Windows-specific.

Parameters

filename	object containing the filename path to file
modes	"r", "w" or "a" with possible modifiers "+", "b"

Returns: true if stream was successfully created, false otherwise, in which case the error code is set.

◆ fprintf()

int OFFile::fprintf	(	const char *	format,
			...
	)

inline

print formatted string into stream, see printf(3)

Parameters

format	format string
...	further parameters according to format string

Returns: number of characters printed

◆ fputc()

int OFFile::fputc ( int c )

inline

writes the character c, cast to an unsigned char, to stream.

Parameters

c character

Returns: the character written as an unsigned char cast to an int or EOF on error

◆ fputs()

int OFFile::fputs ( const char * s )

inline

writes the string s to stream, without its trailing '\0'.

Parameters

s	string to be written

Returns: a non-negative number on success, or EOF on error.

◆ fputwc()

wint_t OFFile::fputwc ( wchar_t wc )

inline

writes the wide character wc to stream.

If ferror(stream) becomes true, it returns WEOF. If a wide character conversion error occurs, it sets the error code to EILSEQ and returns WEOF. Otherwise it returns wc.

Parameters

wc	wide character to write to stream

Returns: character written or WEOF

◆ fread()

size_t OFFile::fread	(	void *	ptr,
		size_t	size,
		size_t	n
	)

inline

reads n elements of data, each size bytes long, from the stream, storing them at the location given by ptr.

Returns the number of items successfully read (i.e., not the number of characters). If an error occurs, or the end-of-file is reached, the return value is a short item count (or zero). fread does not distinguish between end-of-file and error, and callers must use feof and ferror to determine which occurred.

Parameters

ptr	pointer to buffer
size	size of item
n	number of items

Returns: number of items read

◆ freopen()

OFBool OFFile::freopen	(	const char *	filename,
		const char *	modes
	)

inline

opens the file whose name is the string pointed to by path and associates the stream pointed maintained by this object with it.

The original stream (if it exists) is closed. The mode argument is used just as in the fopen function. The primary use of the freopen function is to change the file associated with a standard text stream (stderr, stdin, or stdout).

Parameters

filename	path to file
modes	"r", "w" or "a" with possible modifiers "+", "b"

Returns: true if stream was successfully created, false otherwise, in which case the error code is set.

◆ fseek()

int OFFile::fseek	(	offile_off_t	off,
		int	whence
	)

inline

sets the file position indicator for the stream pointed to by stream.

The new position, measured in bytes, is obtained by adding offset bytes to the position specified by whence. If whence is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively. A successful call to the fseek function clears the end-of- file indicator for the stream and undoes any effects of the ungetc function on the same stream.

Parameters

off	offset to seek to
whence	SEEK_SET, SEEK_CUR, or SEEK_END

Returns: 0 upon success, -1 otherwise in which case the error code is set.

◆ fsetpos()

int OFFile::fsetpos ( offile_fpos_t * pos )

inline

alternate interface equivalent to fseek (with whence set to SEEK_SET), setting the current value of the file offset from the object referenced by pos.

On some non-UNIX systems an fpos_t object may be a complex object and these routines may be the only way to portably reposition a text stream.

Parameters

pos	pointer to offile_fpos_t structure

Returns: 0 upon success, -1 otherwise in which case the error code is set.

◆ ftell()

offile_off_t OFFile::ftell ( )

inline

obtains the current value of the file position indicator for the stream pointed to by the stream.

Returns: current file position

◆ fwide()

int OFFile::fwide ( int mode )

inline

When mode is zero, the fwide function determines the current orientation of stream.

It returns a value > 0 if stream is wide-character oriented, i.e. if wide character I/O is permitted but char I/O is disallowed. It returns a value < 0 if stream is byte oriented, i.e. if char I/O is permitted but wide character I/O is disallowed. It returns zero if stream has no orientation yet; in this case the next I/O operation might change the orientation (to byte oriented if it is a char I/O operation, or to wide-character oriented if it is a wide character I/O operation). Once a stream has an orientation, it cannot be changed and persists until the stream is closed. When mode is non-zero, the fwide function first attempts to set stream's orientation (to wide-character oriented if mode > 0, or to byte oriented if mode < 0). It then returns a value denoting the current orientation, as above.

Parameters

mode	mode of operation for fwide

Returns: orientation of stream

◆ fwprintf()

int OFFile::fwprintf	(	const wchar_t *	format,
			...
	)

inline

print formatted wide string into stream, see wprintf(3)

Parameters

format	format string
...	further parameters according to format string

Returns: number of characters printed

◆ fwrite()

size_t OFFile::fwrite	(	const void *	ptr,
		size_t	size,
		size_t	n
	)

inline

writes n elements of data, each size bytes long, to the stream, obtaining them from the location given by ptr.

Returns the number of items successfully written (i.e., not the number of characters). If an error occurs the return value is a short item count (or zero).

Parameters

ptr	pointer to buffer
size	size of item
n	number of items

Returns: number of items written

◆ getLastError()

offile_errno_t OFFile::getLastError ( ) const

inline

return last error code for this stream

Returns: last error code for this stream

◆ getLastErrorString()

void OFFile::getLastErrorString ( OFString & s ) const

inline

return string describing last error code for this stream

Parameters

s	string describing last error code for this stream returned in this parameter

References OFStandard::strerror().

◆ open()

OFBool OFFile::open ( ) const

inline

return true if this object is currently associated with a stream, false otherwise

Returns: true if this object is currently associated with a stream, false otherwise

◆ pclose()

int OFFile::pclose ( )

inline

waits for the associated process (created with popen) to terminate and returns the exit status of the command as returned by wait4.

In this implementation, fclose and pclose can be used synonymously.

Returns: process ID of the child which exited, or -1 on error, in which case the error code is set

◆ popen()

OFBool OFFile::popen	(	const char *	command,
		const char *	modes
	)

opens a process by creating a pipe, forking, and invoking the shell.

Since a pipe is by definition unidirectional, the type argument may specify only reading or writing, not both; the resulting stream is correspondingly read-only or write-only. If the object was already associated with another file or pipe, that one is closed.

Parameters

command	shell command line
modes	"r" or "w"

Returns: true if pipe was successfully created, false otherwise

◆ rewind()

void OFFile::rewind ( )

inline

sets the file position indicator for the stream pointed to by stream to the beginning of the file.

This is equivalent to fseek(0, SEEK_SET) except that the error indicator for the stream is also cleared.

◆ setbuf()

void OFFile::setbuf ( char * buf )

inline

The three types of buffering available are unbuffered, block buffered, and line buffered.

When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is block buffered many characters are saved up and written as a block; when it is line buffered characters are saved up until a newline is output or input is read from any stream attached to a terminal device (typically stdin). Normally all files are block buffered. if a stream refers to a terminal (as stdout normally does) it is line buffered. The standard error stream stderr is always unbuffered by default. This function allows to set the mode of the stream to unbuffered (if buf is NULL) or block buffered.

Parameters

buf	pointer to buffer of size BUFSIZ as declared in cstdio, or NULL

Returns: 0 upon success, nonzero otherwise, in which case the error code may be set

◆ setbuffer()

void OFFile::setbuffer	(	char *	buf,
		size_t	size
	)

inline

The three types of buffering available are unbuffered, block buffered, and line buffered.

When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is block buffered many characters are saved up and written as a block; when it is line buffered characters are saved up until a newline is output or input is read from any stream attached to a terminal device (typically stdin). Normally all files are block buffered. if a stream refers to a terminal (as stdout normally does) it is line buffered. The standard error stream stderr is always unbuffered by default. This function allows to set the mode of the stream to unbuffered (if buf is NULL) or block buffered.

Parameters

buf	pointer to buffer
size	size of buffer, in bytes

Returns: 0 upon success, nonzero otherwise, in which case the error code may be set

◆ setlinebuf()

void OFFile::setlinebuf ( )

inline

The three types of buffering available are unbuffered, block buffered, and line buffered.

When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is block buffered many characters are saved up and written as a block; when it is line buffered characters are saved up until a newline is output or input is read from any stream attached to a terminal device (typically stdin). Normally all files are block buffered. if a stream refers to a terminal (as stdout normally does) it is line buffered. The standard error stream stderr is always unbuffered by default. this function allows to set the mode of the stream to line buffered.

Returns: 0 upon success, nonzero otherwise, in which case the error code may be set

◆ setvbuf()

int OFFile::setvbuf	(	char *	buf,
		int	modes,
		size_t	n
	)

inline

The three types of buffering available are unbuffered, block buffered, and line buffered.

When an output stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is block buffered many characters are saved up and written as a block; when it is line buffered characters are saved up until a newline is output or input is read from any stream attached to a terminal device (typically stdin). Normally all files are block buffered. if a stream refers to a terminal (as stdout normally does) it is line buffered. The standard error stream stderr is always unbuffered by default. This function allows to set the stream mode.

Parameters

buf	pointer to buffer, may be NULL
modes	_IONBF (unbuffered) _IOLBF (line buffered) or _IOFBF (fully buffered)
n	size of buffer, in bytes

Returns: 0 upon success, nonzero otherwise, in which case the error code may be set

◆ tmpfile()

OFBool OFFile::tmpfile ( )

inline

generates a unique temporary filename.

The temporary file is then opened in binary read/write (w+b) mode. The file will be automatically deleted when it is closed or the program terminates normally.

Returns: true if stream was successfully created, false otherwise, in which case the error code is set.

◆ ungetc()

int OFFile::ungetc ( int c )

inline

pushes c back to stream, cast to unsigned char, where it is available for subsequent read operations.

Pushed - back characters will be returned in reverse order; only one pushback is guaranteed.

Parameters

c	character to push back

Returns: c on success, or EOF on error.

◆ ungetwc()

wint_t OFFile::ungetwc ( wint_t wc )

inline

pushes back a wide character onto stream and returns it.

If wc is WEOF, it returns WEOF. If wc is an invalid wide character, it sets errno to EILSEQ and returns WEOF. If wc is a valid wide character, it is pushed back onto the stream and thus becomes available for future wide character read operations. The file-position indicator is decremented by one or more. The end-of-file indicator is cleared. The backing storage of the file is not affected. Note: wc need not be the last wide character read from the stream; it can be any other valid wide character. If the implementation supports multiple push-back operations in a row, the pushed-back wide characters will be read in reverse order; however, only one level of push-back is guaranteed.

Parameters

wc	wide character to put back to stream

Returns: character put back or WEOF

◆ vfprintf()

int OFFile::vfprintf	(	const char *	format,
		va_list	arg
	)

inline

print formatted string into stream, see printf(3)

Parameters

format	format string
arg	list of further parameters according to format string

Returns: number of characters printed

◆ vfwprintf()

int OFFile::vfwprintf	(	const wchar_t *	format,
		va_list	arg
	)

inline

print formatted wide string into stream, see printf(3)

Parameters

format	format string
arg	list of further parameters according to format string

Returns: number of characters printed

◆ wfopen()

OFBool OFFile::wfopen	(	const wchar_t *	filename,
		const wchar_t *	modes
	)

inline

opens the file whose name is the wide character string pointed to by path and associates a stream with it.

Remarks: This member is only available if DCMTK is compiled on Windows Operating Systems with wide chars enabled (defining _WIN32 as well as WIDE_CHAR_FILE_IO_FUNCTIONS).

Parameters

filename	Unicode filename path to file
modes	"r", "w" or "a" with possible modifiers "+", "b", as a wide character string

Returns: true if stream was successfully created, false otherwise, in which case the error code is set.

The documentation for this class was generated from the following file:

ofstd/include/dcmtk/ofstd/offile.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ OFFile()

Member Function Documentation

◆ eof()

◆ error()

◆ fclose()

◆ fdopen()

◆ fflush()

◆ fgetc()

◆ fgetpos()

◆ fgets()

◆ fgetwc()

◆ file()

◆ fileNo()

◆ fopen() [1/2]

◆ fopen() [2/2]

◆ fprintf()

◆ fputc()

◆ fputs()

◆ fputwc()

◆ fread()

◆ freopen()

◆ fseek()

◆ fsetpos()

◆ ftell()

◆ fwide()

◆ fwprintf()

◆ fwrite()

◆ getLastError()

◆ getLastErrorString()

◆ open()

◆ pclose()

◆ popen()

◆ rewind()

◆ setbuf()

◆ setbuffer()

◆ setlinebuf()

◆ setvbuf()

◆ tmpfile()

◆ ungetc()

◆ ungetwc()

◆ vfprintf()

◆ vfwprintf()

◆ wfopen()