cgul_libc_cxx Class Reference

C++ bindings for cgul_libc More...

#include <cgul_libc_cxx.h>

Collaboration diagram for cgul_libc_cxx:
Collaboration graph

Static Public Member Functions

static void set_out_of_memory (int out_of_memory)
 
static void * calloc (size_t element_count, size_t element_size)
 
static void * malloc (size_t new_size)
 
static void * realloc (void *orig_pointer, size_t new_size)
 
static void * memset (void *buf, int c, size_t n)
 
static void * memcpy (void *dst, const void *src, size_t n)
 
static void * memmove (void *dst, const void *src, size_t n)
 
static FILE * fopen (const char *fname, const char *mode)
 
static FILE * freopen (const char *fname, const char *mode, FILE *f)
 
static void fclose (FILE *f)
 
static void fflush (FILE *f)
 
static size_t fread (void *buf, size_t element_size, size_t element_count, FILE *f)
 
static size_t fwrite (const void *buf, size_t element_size, size_t element_count, FILE *f)
 
static size_t fwrite_block (const void *block, size_t block_size, FILE *fout)
 
static void load_file (FILE *fin, char **ptr, size_t *length)
 
static void load_fname (const char *fname, char **ptr, size_t *length)
 
static void save_file (FILE *fout, const char *block, size_t block_size)
 
static void save_fname (const char *fname, const char *block, size_t block_size)
 
static void copy_file (FILE *fin, FILE *fout)
 
static long ftell (FILE *f)
 
static void fseek (FILE *f, long offset, int whence)
 
static void rewind (FILE *f)
 
static void fgetpos (FILE *f, fpos_t *pos)
 
static void fsetpos (FILE *f, fpos_t *pos)
 
static FILE * tmpfile ()
 
static int printf (const char *format,...)
 
static int vprintf (const char *format, va_list args)
 
static int fprintf (FILE *f, const char *format,...)
 
static int vfprintf (FILE *f, const char *format, va_list args)
 
static int fgetc (FILE *f)
 
static void fputc (int c, FILE *f)
 
static char * fgets (char *buf, int buf_size, FILE *f)
 
static void fputs (const char *s, FILE *f)
 
static void puts (const char *s)
 
static size_t strlen (const char *s)
 
static char * strcpy (char *dst, const char *src)
 
static char * strncpy (char *dst, const char *src, size_t dst_size)
 
static char * strcat (char *dst, const char *src)
 
static int strcmp (const char *s1, const char *s2)
 
static char * strdup (const char *s)
 
static int snprintf (char *dst, long dst_size, const char *format,...)
 
static int vsnprintf (char *dst, long dst_size, const char *format, va_list args)
 
static char * asprintf (const char *format,...)
 
static char * vasprintf (const char *format, va_list args)
 
static char * basename (const char *name)
 
static char * dirname (const char *name)
 
static char * extension (const char *name)
 
static char * rootname (const char *name)
 
static int strip_utf8_byte_order_mark (FILE *f)
 

Detailed Description

This class provides the C++ bindings for C cgul_libc. The main purpose of this class is to convert the C-style function calls and exception handling in cgul_libc into C++-style function calls and exception handling.

Member Function Documentation

§ set_out_of_memory()

static void cgul_libc_cxx::set_out_of_memory ( int  out_of_memory)
inlinestatic

This method lets you test out-of-memory exception handling by forcing cgul_libc__calloc(), cgul_libc__malloc(), and cgul_libc__realloc() to skip memory allocation and immediately return NULL. You should set out_of_memory immediately before the allocation call you want to test and clear it immediately after.

Parameters
[in]out_of_memorywhether to simulate out-of-memory condition

References cgul_libc__set_out_of_memory().

§ calloc()

static void* cgul_libc_cxx::calloc ( size_t  element_count,
size_t  element_size 
)
inlinestatic

Wrapper for calloc(). On success, a pointer to a block of memory that is large enough to hold an array of element_count elements is returned. The block of memory is initialized with all zeros, and the client must call free() on the value returned. On failure, an exception is thrown, and NULL is returned.

Parameters
[in]element_countnumber of elements to allocate space for
[in]element_sizesize of one element
Returns
pointer to a block of memory

References cgul_libc__calloc().

§ malloc()

static void* cgul_libc_cxx::malloc ( size_t  new_size)
inlinestatic

Wrapper for malloc(). On success, a pointer to a block of memory that is new_size bytes long is returned uninitialized, and the client must call free() on the value returned. On failure, an exception is thrown, and NULL is returned.

Parameters
[in]new_sizenew size for the block of memory to return
Returns
point to a block of memory

References cgul_libc__malloc().

§ realloc()

static void* cgul_libc_cxx::realloc ( void *  orig_pointer,
size_t  new_size 
)
inlinestatic

Wrapper for realloc(). On success, a pointer to memory that holds new_size bytes is returned, and the client must eventually call free() on the value returned. The client must not call free() on orig_pointer if this function returns successfully.

If an error occurs, an exception will be thrown, and the client will still need to call free() on orig_pointer. (Notice that this is different behavior from realloc() which returns NULL if an error occurs.)

Parameters
[in]orig_pointeroriginal pointer
[in]new_sizenew size for the pointer that is returned
Returns
pointer to a block of memory

References cgul_libc__realloc().

§ memset()

static void* cgul_libc_cxx::memset ( void *  buf,
int  c,
size_t  n 
)
inlinestatic

Wrapper for memset(). Set a region of memory pointed to by buf by repeatedly copying c.

Parameters
[in]bufbuffer where memory will be set
[in]cbyte repeatedly used to set the memory region
[in]nbuffer size
Returns
buf

References cgul_libc__memset().

§ memcpy()

static void* cgul_libc_cxx::memcpy ( void *  dst,
const void *  src,
size_t  n 
)
inlinestatic

Wrapper for memcpy(). Copy the first n bytes from the src buffer to the dst buffer. It is important that the src and dst buffers do not overlap. If they do, you should use memmove() instead.

Parameters
[in]dstdestination buffer
[in]srcsource buffer
[in]nbuffer size
Returns
dst

References cgul_libc__memcpy().

§ memmove()

static void* cgul_libc_cxx::memmove ( void *  dst,
const void *  src,
size_t  n 
)
inlinestatic

Wrapper for memmove(). Copy the first n bytes from the src buffer to the dst buffer. The src and dst buffers may overlap.

Parameters
[in]dstdestination buffer
[in]srcsource buffer
[in]nbuffer size
Returns
dst

References cgul_libc__memmove().

§ fopen()

static FILE* cgul_libc_cxx::fopen ( const char *  fname,
const char *  mode 
)
inlinestatic

Wrapper for fopen(). It opens the file with name fname using the mode specified by mode. If an error occurs, an exception is thrown.

Parameters
[in]fnamefile name
[in]modeopen file mode
Returns
opened file

References cgul_libc__fopen().

§ freopen()

static FILE* cgul_libc_cxx::freopen ( const char *  fname,
const char *  mode,
FILE *  f 
)
inlinestatic

Wrapper for freopen(). It reopens f so that the underlying file descriptor points to fname opened using mode. If an error occurs, an exception is thrown.

Parameters
[in]fnamefile name
[in]modeopen file mode
[in]ffile object to reopen
Returns
opened file

References cgul_libc__freopen().

§ fclose()

static void cgul_libc_cxx::fclose ( FILE *  f)
inlinestatic

Wrapper for fclose(). It closes f. If an error occurs, an exception is thrown. You should be careful using this function because you will almost always want to close files if the main part of your code throws an exception. Thus, if the stack is unwinding, to avoid this function from overwriting the current exception, you should probably call fclose() directly instead of calling this function.

Parameters
[in]ffile object to close

References cgul_libc__fclose().

§ fflush()

static void cgul_libc_cxx::fflush ( FILE *  f)
inlinestatic

Wrapper for fflush(). It flushes the file f, or if f is NULL, it flushes all open files. If an error occurs, an exception is thrown.

Parameters
[in]ffile object to close

References cgul_libc__fflush().

§ fread()

static size_t cgul_libc_cxx::fread ( void *  buf,
size_t  element_size,
size_t  element_count,
FILE *  f 
)
inlinestatic

Wrapper for fread(). It reads element_count elements of size element_size each into buf from f. On success, the number of elements read (which is not necessarily the same as the number of bytes read) is returned. If EOF is reached, a byte count of 0 is returned. On failure, an exception is thrown.

Parameters
[in]bufdestination buffer
[in]element_sizesize of each element to read
[in]element_countnumber of elements to read
[in]ffile from which to read
Returns
number of elements read

References cgul_libc__fread().

§ fwrite()

static size_t cgul_libc_cxx::fwrite ( const void *  buf,
size_t  element_size,
size_t  element_count,
FILE *  f 
)
inlinestatic

Wrapper for fwrite(). It writes element_count elements of size element_size each from buf into f. On success, the number of elements written (which is not necessarily the same as the number of bytes written) is returned. On failure, an exception is thrown.

Parameters
[in]bufsource buffer
[in]element_sizesize of each element to write
[in]element_countnumber of elements to write
[in]ffile to which to write
Returns
number of elements written
See also
fwrite_block()

References cgul_libc__fwrite().

§ fwrite_block()

static size_t cgul_libc_cxx::fwrite_block ( const void *  block,
size_t  block_size,
FILE *  fout 
)
inlinestatic

Wrapper for cgul_libc__fwrite_block(). It writes the block block of size block_size bytes to the output file fout. Unlike fwrite(), the write is restarted if interrupted. This function returns the total number of bytes written. If an error occurs, an exception is thrown.

Parameters
[in]blockblock
[in]block_sizesize of block in bytes
[in]foutoutput file
Returns
total number of bytes written
See also
fwrite()

References cgul_libc__fwrite_block().

§ load_file()

static void cgul_libc_cxx::load_file ( FILE *  fin,
char **  ptr,
size_t *  length 
)
inlinestatic

Load the file fin into memory saving a copy of the starting location of the file in memory to *ptr and its length to *length if length is not NULL. The caller is responsible for calling free() on *ptr. If an error occurs, an exception is thrown.

Parameters
[in]fininput file
[out]ptrpointer to in-memory copy of file
[out]lengthlength in bytes of the in-memory copy of the file
See also
save_file()

References cgul_libc__load_file().

§ load_fname()

static void cgul_libc_cxx::load_fname ( const char *  fname,
char **  ptr,
size_t *  length 
)
inlinestatic

Load the file with name fname into memory saving a copy of the starting location of the file in memory to *ptr and its length to *length if length is not NULL. The caller is responsible for calling free() on *ptr. If an error occurs, an exception is thrown.

Parameters
[in]fnamename of input file
[out]ptrpointer to in-memory copy of file
[out]lengthlength in bytes of the in-memory copy of the file
See also
save_fname()

References cgul_libc__load_fname().

§ save_file()

static void cgul_libc_cxx::save_file ( FILE *  fout,
const char *  block,
size_t  block_size 
)
inlinestatic

Save the binary block of memory block extending for block_size bytes to the output file fout. If an error occurs, an exception is thrown.

Parameters
[in]foutoutput file
[in]blockblock
[in]block_sizesize of block in bytes
See also
load_file()

References cgul_libc__save_file().

§ save_fname()

static void cgul_libc_cxx::save_fname ( const char *  fname,
const char *  block,
size_t  block_size 
)
inlinestatic

Save the binary block of memory block extending for block_size bytes to the output file with name fname. If an error occurs, an exception is thrown.

Parameters
[in]fnamename of the output file
[in]blockblock
[in]block_sizesize of block in bytes
See also
load_fname()

References cgul_libc__save_fname().

§ copy_file()

static void cgul_libc_cxx::copy_file ( FILE *  fin,
FILE *  fout 
)
inlinestatic

Copy everything from fin to fout. If an error occurs, an exception is thrown. This is not a wrapper around any libc function.

Parameters
[in]fininput file
[in]foutoutput file

References cgul_libc__copy_file().

§ ftell()

static long cgul_libc_cxx::ftell ( FILE *  f)
inlinestatic

Wrapper for ftell(). On success, the file position of f is returned. On failure, an exception is thrown.

Parameters
[in]ffile
Returns
file position

References cgul_libc__ftell().

§ fseek()

static void cgul_libc_cxx::fseek ( FILE *  f,
long  offset,
int  whence 
)
inlinestatic

Wrapper for fseek(). On success, the file is positioned according to the values of offset and whence where offset is relative to the beginning of the file, the current position, or the end of the file if whence is SEEK_SET, SEEK_CUR, or SEEK_END respectively. On failure, an exception is thrown.

Parameters
[in]ffile
[in]offsetoffset
[in]whenceposition to which offset is relative

References cgul_libc__fseek().

§ rewind()

static void cgul_libc_cxx::rewind ( FILE *  f)
inlinestatic

Wrapper for rewind() to rewind f. An exception is thrown if f is not seekable.

Parameters
[in]ffile

References cgul_libc__rewind().

§ fgetpos()

static void cgul_libc_cxx::fgetpos ( FILE *  f,
fpos_t *  pos 
)
inlinestatic

Wrapper for fgetpos(). On success, the current file position for f is stored in pos pos. On failure, an exception is thrown.

Parameters
[in]ffile
[out]poscurrent file position

References cgul_libc__fgetpos().

§ fsetpos()

static void cgul_libc_cxx::fsetpos ( FILE *  f,
fpos_t *  pos 
)
inlinestatic

Wrapper for fsetpos(). On success, the current file position for f is set to pos. On failure, an exception is thrown.

Parameters
[in]ffile
[out]poscurrent file position

References cgul_libc__fsetpos().

§ tmpfile()

static FILE* cgul_libc_cxx::tmpfile ( )
inlinestatic

Wrapper for tmpfile(). On success, a file opened for reading and writting is returned. On failure, an exception is thrown. When opening a file using glibc-2.3.4, strace returned the following which says the file is opened without race conditions and is immediately unlinked so that the file is removed even if your program exits unexpectedly:

    open("/tmp/tmpfGQda9F", O_RDWR|O_CREAT|O_EXCL, 0600) = 3
    unlink("/tmp/tmpfGQda9F")               = 0
Returns
temporary file

References cgul_libc__tmpfile().

§ printf()

static int cgul_libc_cxx::printf ( const char *  format,
  ... 
)
inlinestatic

Wrapper for vprintf(). On success, the number of characters printed to stdout is returned. On failure, an exception is thrown.

Parameters
[in]formatformat string
[in]...variable argument list that matches format
Returns
number of characters read

References cgul_libc__vprintf().

§ vprintf()

static int cgul_libc_cxx::vprintf ( const char *  format,
va_list  args 
)
inlinestatic

Wrapper for vprintf(). On success, the number of characters printed to stdout is returned. On failure, an exception is thrown.

Parameters
[in]formatformat string
[in]argsvariable argument list that matches format
Returns
number of characters read

References cgul_libc__vprintf().

§ fprintf()

static int cgul_libc_cxx::fprintf ( FILE *  f,
const char *  format,
  ... 
)
inlinestatic

Wrapper for vfprintf(). On success, the number of characters printed to f is returned. On failure, an exception is thrown.

Parameters
[in]foutput file
[in]formatformat string
[in]...variable argument list that matches format
Returns
number of characters read

References cgul_libc__vfprintf().

§ vfprintf()

static int cgul_libc_cxx::vfprintf ( FILE *  f,
const char *  format,
va_list  args 
)
inlinestatic

Wrapper for vfprintf(). On success, the number of characters printed to f is returned. On failure, an exception is thrown.

Parameters
[in]foutput file
[in]formatformat string
[in]argsvariable argument list that matches format
Returns
number of characters read

References cgul_libc__vfprintf().

§ fgetc()

static int cgul_libc_cxx::fgetc ( FILE *  f)
inlinestatic

Wrapper for fgetc(). Return the next character from f. If the EOF is reached, EOF is returned. If an error occurs, an exception is thrown.

Parameters
[in]finput file
Returns
character read from f

References cgul_libc__fgetc().

§ fputc()

static void cgul_libc_cxx::fputc ( int  c,
FILE *  f 
)
inlinestatic

Wrapper for fputc(). Cast c to an unsigned char and write it to f. If an error occurs, an exception is thrown.

Parameters
[in]ccharacter to write
[in]foutput file

References cgul_libc__fputc().

§ fgets()

static char* cgul_libc_cxx::fgets ( char *  buf,
int  buf_size,
FILE *  f 
)
inlinestatic

Wrapper for fgets(). Read a string from f. The string will be returned in buf and will be null terminated. The string is limited to buf_size - 1 or the first '\n' character. On success, buf is returned. If EOF is reached, NULL is returned. If an error occurs, an exception is thrown.

Parameters
[in]bufbuffer where string is stored
[in]buf_sizesize of buf
[in]finput file
Returns
buf on success or NULL on EOF

References cgul_libc__fgets().

§ fputs()

static void cgul_libc_cxx::fputs ( const char *  s,
FILE *  f 
)
inlinestatic

Wrapper for fputs. Write s to f. If an error occurs, an exception is thrown.

Parameters
[in]sstring
[in]ffile to which s is written

References cgul_libc__fputs().

§ puts()

static void cgul_libc_cxx::puts ( const char *  s)
inlinestatic

Wrapper for puts. It writes the string s to stdout. If an error occurs, an exception is thrown.

Parameters
[in]sstring to write

References cgul_libc__puts().

§ strlen()

static size_t cgul_libc_cxx::strlen ( const char *  s)
inlinestatic

Wrapper for strlen() to determine the string length of s.

Parameters
[in]sstring
Returns
length of s

References cgul_libc__strlen().

§ strcpy()

static char* cgul_libc_cxx::strcpy ( char *  dst,
const char *  src 
)
inlinestatic

Wrapper for strcpy() to copy src to dst.

Parameters
[in]dstdestination string
[in]srcsource string
Returns
dst

References cgul_libc__strcpy().

§ strncpy()

static char* cgul_libc_cxx::strncpy ( char *  dst,
const char *  src,
size_t  dst_size 
)
inlinestatic

This method implements strncpy() functionality except it always null terminates the result.

Parameters
[in]dstdestination string
[in]dst_sizesize in bytes of dst
[in]srcsource string
Returns
dst

References cgul_libc__strncpy().

§ strcat()

static char* cgul_libc_cxx::strcat ( char *  dst,
const char *  src 
)
inlinestatic

Wrapper for strcpy() to concatenate src with dst.

Parameters
[in]dstdestination string
[in]srcsource string
Returns
dst

References cgul_libc__strcat().

§ strcmp()

static int cgul_libc_cxx::strcmp ( const char *  s1,
const char *  s2 
)
inlinestatic

Wrapper for strcmp(). It compares s1 with s2 and returns less than zero if s1 is less than s2. It returns greater than zero if s1 is greater than s2, and it returns zero if s1 is equal to s2.

Parameters
s1first string to compare
s2second string to compare
Returns
result of comparison

References cgul_libc__strcmp().

§ strdup()

static char* cgul_libc_cxx::strdup ( const char *  s)
inlinestatic

Return a duplicate of s. The client is responsible for calling free() on the pointer returned. If an error occurs, an exception is thrown. This is not a wrapper around strdup() because strdup() is not portable.

Parameters
[in]sstring to duplicate
Returns
duplicate string

References cgul_libc__strdup().

§ snprintf()

static int cgul_libc_cxx::snprintf ( char *  dst,
long  dst_size,
const char *  format,
  ... 
)
inlinestatic

This function is a thin wrapper around cgul_libc__vsnprintf().

Parameters
[in]dstdestination string
[in]dst_sizesize of dst
[in]formatformat string
[in]...variable length arguments that match format
Returns
length of the string copied to dst
See also
cgul_libc__vsnprintf

References cgul_libc__vsnprintf().

§ vsnprintf()

static int cgul_libc_cxx::vsnprintf ( char *  dst,
long  dst_size,
const char *  format,
va_list  args 
)
inlinestatic

This function is not a wrapper around snprintf() because snprintf() is not generally portable. Instead, this function uses the sprintf()-like implementation provided by cgul_string__append_vsprintf().

This function expands format and writes up to a maximum of dst_size - 1 bytes to dst truncating the expanded string if necessary. It always null-terminates dst. On success, the entire length of the expanded string is returned even if dst only holds a truncated version of that string. On failure, an exception is thrown.

NOTE: If you pass in 0 for dst_size and (optionally) NULL for dst, this function will not attempt to alter dst, but it will return the full length of the expanded format string. You can use this return value to allocate the right amount of space so that you can turn around and call cgul_libc__vsprintf(). However, you are probably better off calling cgul_libc__asprintf() which does the allocation and format string expansion in a single call.

Parameters
[in]dstdestination string
[in]dst_sizesize of dst
[in]formatformat string
[in]argsvariable length arguments that match format
Returns
length of the string copied to dst
See also
cgul_libc__asprintf

References cgul_libc__vsnprintf().

§ asprintf()

static char* cgul_libc_cxx::asprintf ( const char *  format,
  ... 
)
inlinestatic

This function is a thin wrapper around cgul_libc__vasprintf().

Parameters
[in]formatformat string
[in]...variable arguments that match format
Returns
newly allocated and formatted string

References cgul_libc__vasprintf().

§ vasprintf()

static char* cgul_libc_cxx::vasprintf ( const char *  format,
va_list  args 
)
inlinestatic

This function mimics the BSD vasprintf() function by allocating enough memory before calling sprintf() to guarantee that no buffer overflows occur. The caller is responsible for calling free() on the pointer returned. If this method fails, an exception is thrown.

Parameters
[in]formatformat string
[in]argsvariable arguments that match format
Returns
newly allocated and formatted string

References cgul_libc__vasprintf().

§ basename()

static char* cgul_libc_cxx::basename ( const char *  name)
inlinestatic

Get the base name of name. It returns everything after the last slash or the last backslash. If no slash or backslash can be found, it simply returns name. The client is responsible for calling free() on the pointer returned. If memory cannot be allocated, an exception is thrown.

Parameters
[in]namename of file
Returns
base name of name

References cgul_libc__basename().

§ dirname()

static char* cgul_libc_cxx::dirname ( const char *  name)
inlinestatic

Get the directory name of name. It returns everything before the last slash or the last backslash. If no slash or backslash can be found, it simply returns ".". The client is responsible for calling free() on the pointer returned. If memory cannot be allocated, an exception is thrown.

Parameters
[in]namename of file
Returns
directory name of name

References cgul_libc__dirname().

§ extension()

static char* cgul_libc_cxx::extension ( const char *  name)
inlinestatic

Get the file extension of the base name of name. It returns everything after and including the last dot in the base name of name. If no dot can be found, it simply returns an empty string. The client is responsible for calling free() on the pointer returned. If memory cannot be allocated, an exception is thrown.

For example, the base name of "/foo/bar.d/" is "bar.d" (despite the trailing path separator). Thus, the extension is ".d". This differs from how the Tcl "file extension" command works which returns an empty string in this case (because of the path separator).

Parameters
[in]namename of file
Returns
file extension of name
See also
rootname()

References cgul_libc__extension().

§ rootname()

static char* cgul_libc_cxx::rootname ( const char *  name)
inlinestatic

Get the root name of name. This function joins the directory name and base name of name after stripping off the extension. The client is responsible for calling free() on the pointer returned. If memory cannot be allocated, an exception is thrown.

For example, the base name of "/foo/bar.d/" is "bar.d" (despite the trailing path separator). Thus, the extension is ".d" and the root name is "/foo/bar". This differs from how the Tcl "file extension" command works which returns "/foo/bar.d/" n this case (because of the path separator).

Parameters
[in]namename of file
Returns
root name of name

References cgul_libc__rootname().

§ strip_utf8_byte_order_mark()

static int cgul_libc_cxx::strip_utf8_byte_order_mark ( FILE *  f)
inlinestatic

This method strips the UTF-8 Byte-Order Mark (BOM) from f. This method returns 1 if the BOM is stripped; otherwise, it returns 0. If an error occurs, an exception is thrown.

IMPORTANT: Because of the way this method is written, it can only be called on files that allow random access. Do not try to use it on stdin for example.

Parameters
[in]ffile
Returns
whether the utf8 byte order mark was stripped

References cgul_libc__strip_utf8_byte_order_mark().


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