OFFile Class Reference

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

List of all members.

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
 ~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.
OFBool fdopen (int fd, const char *modes)
 associates a stream with the existing file descriptor, fildes.
OFBool popen (const char *command, const char *modes)
 opens a process by creating a pipe, forking, and invoking the shell.
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.
OFBool tmpfile ()
 generates a unique temporary filename.
int fclose ()
 dissociates the named stream from its underlying file or set of functions.
int pclose ()
 waits for the associated process (created with popen) to terminate and returns the exit status of the command as returned by wait4.
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.
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.
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.
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.
void setlinebuf ()
 The three types of buffering available are unbuffered, block buffered, and line buffered.
void rewind ()
 sets the file position indicator for the stream pointed to by stream to the beginning of the file.
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.
int error ()
 tests the error indicator for the stream, returning non-zero if it is set.
int fileNo ()
 returns the low-level file descriptor associated with the stream.
void setbuf (char *buf)
 The three types of buffering available are unbuffered, block buffered, and line buffered.
int setvbuf (char *buf, int modes, size_t n)
 The three types of buffering available are unbuffered, block buffered, and line buffered.
void setbuffer (char *buf, size_t size)
 The three types of buffering available are unbuffered, block buffered, and line buffered.
int fputc (int c)
 writes the character c, cast to an unsigned char, to stream.
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.
int fputs (const char *s)
 writes the string s to stream, without its trailing '\0'.
int ungetc (int c)
 pushes c back to stream, cast to unsigned char, where it is available for subsequent read operations.
int fseek (offile_off_t off, int whence)
 sets the file position indicator for the stream pointed to by stream.
offile_off_t ftell ()
 obtains the current value of the file position indicator for the stream pointed to by the stream.
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.
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.
int fprintf (const char *format,...)
 print formatted string into stream, see printf(3)
int vfprintf (const char *format, va_list arg)
 print formatted string into stream, see printf(3)
FILE * file ()
 return FILE pointer managed by this object.
OFBool open () const
 return true if this object is currently associated with a stream, false otherwise
offile_errno_t getLastError () const
 return last error code for this stream
void getLastErrorString (OFString &s) const
 return string describing last error code for this stream

Private Member Functions

 OFFile (const OFFile &arg)
OFFileoperator= (const OFFile &arg)
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.

Definition at line 115 of file offile.h.


Constructor & Destructor Documentation

OFFile::OFFile ( FILE *  f  )  [inline]

create object for given stdio FILE

Parameters:
f stdio FILE

Definition at line 124 of file offile.h.


Member Function Documentation

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.

Definition at line 139 of file offile.h.

References fclose(), file_, popened_, and storeLastError().

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

associates a stream with the existing file descriptor, fildes.

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 belong­ ing to fildes, 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.

Definition at line 179 of file offile.h.

References fclose(), file_, popened_, and storeLastError().

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

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

Definition at line 196 of file offile.h.

References fclose(), file_, popened_, and storeLastError().

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.

Definition at line 217 of file offile.h.

References file_, popened_, and storeLastError().

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.

Definition at line 234 of file offile.h.

References fclose(), file_, popened_, and storeLastError().

int OFFile::fclose (  )  [inline]

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.

Definition at line 254 of file offile.h.

References file_, pclose(), popened_, and storeLastError().

Referenced by fdopen(), fopen(), pclose(), popen(), tmpfile(), and ~OFFile().

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

Definition at line 283 of file offile.h.

References fclose().

Referenced by fclose().

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

Definition at line 294 of file offile.h.

References file_.

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

Definition at line 310 of file offile.h.

References file_.

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.

Definition at line 320 of file offile.h.

References file_, and storeLastError().

Referenced by fseek().

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

Definition at line 331 of file offile.h.

References file_.

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

Definition at line 346 of file offile.h.

References file_, and setvbuf().

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.

Definition at line 359 of file offile.h.

References file_.

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

Definition at line 371 of file offile.h.

References file_.

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

Definition at line 387 of file offile.h.

References file_.

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

Definition at line 406 of file offile.h.

References file_.

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

Definition at line 422 of file offile.h.

References file_.

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

Definition at line 439 of file offile.h.

References file_, and storeLastError().

Referenced by setbuffer(), and setlinebuf().

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

Definition at line 460 of file offile.h.

References file_, and setvbuf().

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

Definition at line 473 of file offile.h.

References file_.

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

Definition at line 483 of file offile.h.

References file_.

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.

Definition at line 489 of file offile.h.

References file_.

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.

Definition at line 497 of file offile.h.

References file_.

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.

Definition at line 510 of file offile.h.

References fflush(), fgetpos(), file_, fsetpos(), and storeLastError().

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

Definition at line 589 of file offile.h.

References file_, and storeLastError().

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.

Definition at line 626 of file offile.h.

References file_, and storeLastError().

Referenced by fseek().

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.

Definition at line 646 of file offile.h.

References file_, and storeLastError().

Referenced by fseek().

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

Definition at line 664 of file offile.h.

References file_, and 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

Definition at line 679 of file offile.h.

References file_.

Referenced by fprintf().

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

Definition at line 692 of file offile.h.

References file_.

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

Definition at line 697 of file offile.h.

References file_.

offile_errno_t OFFile::getLastError (  )  const [inline]

return last error code for this stream

Returns:
last error code for this stream

Definition at line 702 of file offile.h.

References lasterror_.

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

Definition at line 707 of file offile.h.

References lasterror_, and OFStandard::strerror().


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


Generated on 6 Jan 2011 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.5.1