cgul_libc.h File Reference

wrapper for throwing c-style exceptions from common functions More...

#include "cgul_common.h"
#include "cgul_exception.h"

Include dependency graph for cgul_libc.h:

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

Functions
CGUL_BEGIN_C CGUL_EXPORT void	cgul_libc__set_out_of_memory (cgul_exception_t *cex, int out_of_memory)
CGUL_EXPORT void *	cgul_libc__calloc (cgul_exception_t *cex, size_t element_count, size_t element_size)
CGUL_EXPORT void *	cgul_libc__malloc (cgul_exception_t *cex, size_t new_size)
CGUL_EXPORT void *	cgul_libc__realloc (cgul_exception_t *cex, void *orig_pointer, size_t new_size)
CGUL_EXPORT void *	cgul_libc__memset (cgul_exception_t *cex, void *buf, int c, size_t n)
CGUL_EXPORT void *	cgul_libc__memcpy (cgul_exception_t *cex, void *dst, const void *src, size_t n)
CGUL_EXPORT void *	cgul_libc__memmove (cgul_exception_t *cex, void *dst, const void *src, size_t n)
CGUL_EXPORT FILE *	cgul_libc__fopen (cgul_exception_t *cex, const char *fname, const char *mode)
CGUL_EXPORT FILE *	cgul_libc__freopen (cgul_exception_t *cex, const char *fname, const char *mode, FILE *f)
CGUL_EXPORT void	cgul_libc__fclose (cgul_exception_t *cex, FILE *f)
CGUL_EXPORT void	cgul_libc__fflush (cgul_exception_t *cex, FILE *f)
CGUL_EXPORT size_t	cgul_libc__fread (cgul_exception_t *cex, void *buf, size_t element_size, size_t element_count, FILE *f)
CGUL_EXPORT size_t	cgul_libc__fread_block (cgul_exception_t *cex, void *block, size_t block_size, FILE *fin)
CGUL_EXPORT size_t	cgul_libc__fwrite (cgul_exception_t *cex, const void *buf, size_t element_size, size_t element_count, FILE *f)
CGUL_EXPORT size_t	cgul_libc__fwrite_block (cgul_exception_t *cex, const void *block, size_t block_size, FILE *fout)
CGUL_EXPORT void	cgul_libc__load_file (cgul_exception_t *cex, FILE *fin, char **ptr, size_t *length)
CGUL_EXPORT void	cgul_libc__load_fname (cgul_exception_t *cex, const char *fname, char **ptr, size_t *length)
CGUL_EXPORT void	cgul_libc__save_file (cgul_exception_t *cex, FILE *fout, const char *block, size_t block_size)
CGUL_EXPORT void	cgul_libc__save_fname (cgul_exception_t *cex, const char *fname, const char *block, size_t block_size)
CGUL_EXPORT void	cgul_libc__copy_file (cgul_exception_t *cex, FILE *fin, FILE *fout)
CGUL_EXPORT long	cgul_libc__ftell (cgul_exception_t *cex, FILE *f)
CGUL_EXPORT void	cgul_libc__fseek (cgul_exception_t *cex, FILE *f, long offset, int whence)
CGUL_EXPORT void	cgul_libc__rewind (cgul_exception_t *cex, FILE *f)
CGUL_EXPORT void	cgul_libc__fgetpos (cgul_exception_t *cex, FILE *f, fpos_t *pos)
CGUL_EXPORT void	cgul_libc__fsetpos (cgul_exception_t *cex, FILE *f, fpos_t *pos)
CGUL_EXPORT FILE *	cgul_libc__tmpfile (cgul_exception_t *cex)
CGUL_EXPORT int	cgul_libc__printf (cgul_exception_t *cex, const char *format,...)
CGUL_EXPORT int	cgul_libc__vprintf (cgul_exception_t *cex, const char *format, va_list args)
CGUL_EXPORT int	cgul_libc__fprintf (cgul_exception_t *cex, FILE *f, const char *format,...)
CGUL_EXPORT int	cgul_libc__vfprintf (cgul_exception_t *cex, FILE *f, const char *format, va_list args)
CGUL_EXPORT int	cgul_libc__fgetc (cgul_exception_t *cex, FILE *f)
CGUL_EXPORT void	cgul_libc__fputc (cgul_exception_t *cex, int c, FILE *f)
CGUL_EXPORT char *	cgul_libc__fgets (cgul_exception_t *cex, char *buf, int buf_size, FILE *f)
CGUL_EXPORT void	cgul_libc__fputs (cgul_exception_t *cex, const char *s, FILE *f)
CGUL_EXPORT void	cgul_libc__puts (cgul_exception_t *cex, const char *s)
CGUL_EXPORT size_t	cgul_libc__strlen (cgul_exception_t *cex, const char *s)
CGUL_EXPORT char *	cgul_libc__strcpy (cgul_exception_t *cex, char *dst, const char *src)
CGUL_EXPORT char *	cgul_libc__strncpy (cgul_exception_t *cex, char *dst, const char *src, size_t dst_size)
CGUL_EXPORT char *	cgul_libc__strcat (cgul_exception_t *cex, char *dst, const char *src)
CGUL_EXPORT int	cgul_libc__strcmp (cgul_exception_t *cex, const char *s1, const char *s2)
CGUL_EXPORT char *	cgul_libc__strdup (cgul_exception_t *cex, const char *s)
CGUL_EXPORT int	cgul_libc__snprintf (cgul_exception_t *cex, char *dst, long dst_size, const char *format,...)
CGUL_EXPORT int	cgul_libc__vsnprintf (cgul_exception_t *cex, char *dst, long dst_size, const char *format, va_list args)
CGUL_EXPORT char *	cgul_libc__asprintf (cgul_exception_t *cex, const char *format,...)
CGUL_EXPORT char *	cgul_libc__vasprintf (cgul_exception_t *cex, const char *format, va_list args)
CGUL_EXPORT char *	cgul_libc__basename (cgul_exception_t *cex, const char *name)
CGUL_EXPORT char *	cgul_libc__dirname (cgul_exception_t *cex, const char *name)
CGUL_EXPORT char *	cgul_libc__extension (cgul_exception_t *cex, const char *name)
CGUL_EXPORT char *	cgul_libc__rootname (cgul_exception_t *cex, const char *name)
CGUL_EXPORT int	cgul_libc__strip_utf8_byte_order_mark (cgul_exception_t *cex, FILE *f)

Detailed Description

Wrapper around common functions that converts from tradition c-style error reporting to throwing a c-style exception using cgul_exception.

Author

Paul Serice

Function Documentation

cgul_libc__set_out_of_memory()

CGUL_BEGIN_C CGUL_EXPORT void cgul_libc__set_out_of_memory	(	cgul_exception_t *	cex,
		int	out_of_memory
	)

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]	cex	c-style exception
[in]	out_of_memory	whether to simulate out-of-memory condition

Referenced by cgul_libc_cxx::set_out_of_memory().

cgul_libc__calloc()

CGUL_EXPORT void* cgul_libc__calloc	(	cgul_exception_t *	cex,
		size_t	element_count,
		size_t	element_size
	)

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,out]	cex	c-style exception
[in]	element_count	number of elements to allocate space for
[in]	element_size	size of one element

Returns

pointer to a block of memory

Referenced by cgul_libc_cxx::calloc().

cgul_libc__malloc()

CGUL_EXPORT void* cgul_libc__malloc	(	cgul_exception_t *	cex,
		size_t	new_size
	)

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,out]	cex	c-style exception
[in]	new_size	new size for the block of memory to return

Returns

point to a block of memory

Referenced by cgul_libc_cxx::malloc().

cgul_libc__realloc()

CGUL_EXPORT void* cgul_libc__realloc	(	cgul_exception_t *	cex,
		void *	orig_pointer,
		size_t	new_size
	)

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 orig_pointer will be returned, 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,out]	cex	c-style exception
[in]	orig_pointer	original pointer
[in]	new_size	new size for the pointer that is returned

Returns

pointer to a block of memory

Referenced by cgul_libc_cxx::realloc().

cgul_libc__memset()

CGUL_EXPORT void* cgul_libc__memset	(	cgul_exception_t *	cex,
		void *	buf,
		int	c,
		size_t	n
	)

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

Parameters

[in]	cex	c-style exception
[in]	buf	buffer where memory will be set
[in]	c	byte repeatedly used to set the memory region
[in]	n	buffer size

Returns

buf

Referenced by cgul_libc_cxx::memset().

cgul_libc__memcpy()

CGUL_EXPORT void* cgul_libc__memcpy	(	cgul_exception_t *	cex,
		void *	dst,
		const void *	src,
		size_t	n
	)

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 cgul_libc__memmove() instead.

Parameters

[in]	cex	c-style exception
[in]	dst	destination buffer
[in]	src	source buffer
[in]	n	buffer size

Returns

dst

Referenced by cgul_libc_cxx::memcpy().

cgul_libc__memmove()

CGUL_EXPORT void* cgul_libc__memmove	(	cgul_exception_t *	cex,
		void *	dst,
		const void *	src,
		size_t	n
	)

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]	cex	c-style exception
[in]	dst	destination buffer
[in]	src	source buffer
[in]	n	buffer size

Returns

dst

Referenced by cgul_libc_cxx::memmove().

cgul_libc__fopen()

CGUL_EXPORT FILE* cgul_libc__fopen	(	cgul_exception_t *	cex,
		const char *	fname,
		const char *	mode
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	fname	file name
[in]	mode	open file mode

Returns

opened file

Referenced by cgul_libc_cxx::fopen().

cgul_libc__freopen()

CGUL_EXPORT FILE* cgul_libc__freopen	(	cgul_exception_t *	cex,
		const char *	fname,
		const char *	mode,
		FILE *	f
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	fname	file name
[in]	mode	open file mode
[in]	f	file object to reopen

Returns

opened file

Referenced by cgul_libc_cxx::freopen().

cgul_libc__fclose()

CGUL_EXPORT void cgul_libc__fclose	(	cgul_exception_t *	cex,
		FILE *	f
	)

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,out]	cex	c-style exception
[in]	f	file object to close

Referenced by cgul_libc_cxx::fclose().

cgul_libc__fflush()

CGUL_EXPORT void cgul_libc__fflush	(	cgul_exception_t *	cex,
		FILE *	f
	)

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,out]	cex	c-style exception
[in]	f	file object to close

Referenced by cgul_libc_cxx::fflush().

cgul_libc__fread()

CGUL_EXPORT size_t cgul_libc__fread	(	cgul_exception_t *	cex,
		void *	buf,
		size_t	element_size,
		size_t	element_count,
		FILE *	f
	)

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, (size_t)-1 is returned and an exception is thrown.

Parameters

[in,out]	cex	cex c-style exception
[in]	buf	destination buffer
[in]	element_size	size of each element to read
[in]	element_count	number of elements to read
[in]	f	file from which to read

Returns

number of elements read

See also

cgul_libc__fread_block()

Referenced by cgul_libc_cxx::fread().

cgul_libc__fread_block()

CGUL_EXPORT size_t cgul_libc__fread_block	(	cgul_exception_t *	cex,
		void *	block,
		size_t	block_size,
		FILE *	fin
	)

Read the block block of size block_size bytes from the file fin. Unlike cgul_libc__fread(), the read is restarted if interrupted. This function returns the total number of bytes read. If an error occurs, the total number of bytes read is returned (which could be a short count), and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	block	block
[in]	block_size	size of block in bytes
[in]	fin	input file

Returns

total number of bytes read

See also

cgul_libc__fread()

cgul_libc__fwrite()

CGUL_EXPORT size_t cgul_libc__fwrite	(	cgul_exception_t *	cex,
		const void *	buf,
		size_t	element_size,
		size_t	element_count,
		FILE *	f
	)

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, (size_t)-1 is returned and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	buf	source buffer
[in]	element_size	size of each element to write
[in]	element_count	number of elements to write
[in]	f	file to which to write

Returns

number of elements written

See also

cgul_libc__fwrite_block()

Referenced by cgul_libc_cxx::fwrite().

cgul_libc__fwrite_block()

CGUL_EXPORT size_t cgul_libc__fwrite_block	(	cgul_exception_t *	cex,
		const void *	block,
		size_t	block_size,
		FILE *	fout
	)

Write the block block of size block_size bytes to the output file fout. Unlike cgul_libc__fwrite(), the write is restarted if interrupted. This function returns the total number of bytes written. If an error occurs, the total number of bytes written is returned (which could be a short count), and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	block	block
[in]	block_size	size of block in bytes
[in]	fout	output file

Returns

total number of bytes written

See also

cgul_libc__fwrite()

Referenced by cgul_libc_cxx::fwrite_block().

cgul_libc__load_file()

CGUL_EXPORT void cgul_libc__load_file	(	cgul_exception_t *	cex,
		FILE *	fin,
		char **	ptr,
		size_t *	length
	)

Load the binary 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,out]	cex	c-style exception
[in]	fin	input file
[out]	ptr	pointer to in-memory copy of file
[out]	length	length in bytes of the in-memory copy of the file

See also

cgul_libc__save_file()

Referenced by cgul_libc_cxx::load_file().

cgul_libc__load_fname()

CGUL_EXPORT void cgul_libc__load_fname	(	cgul_exception_t *	cex,
		const char *	fname,
		char **	ptr,
		size_t *	length
	)

Load the binary 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,out]	cex	c-style exception
[in]	fname	name of input file
[out]	ptr	pointer to in-memory copy of file
[out]	length	length in bytes of the in-memory copy of the file

See also

cgul_libc__save_fname()

Referenced by cgul_libc_cxx::load_fname().

cgul_libc__save_file()

CGUL_EXPORT void cgul_libc__save_file	(	cgul_exception_t *	cex,
		FILE *	fout,
		const char *	block,
		size_t	block_size
	)

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,out]	cex	c-style exception
[in]	fout	output file
[in]	block	block
[in]	block_size	size of block in bytes

See also

cgul_libc__load_file()

Referenced by cgul_libc_cxx::save_file().

cgul_libc__save_fname()

CGUL_EXPORT void cgul_libc__save_fname	(	cgul_exception_t *	cex,
		const char *	fname,
		const char *	block,
		size_t	block_size
	)

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,out]	cex	c-style exception
[in]	fname	name of the output file
[in]	block	block
[in]	block_size	size of block in bytes

See also

cgul_libc__load_fname()

Referenced by cgul_libc_cxx::save_fname().

cgul_libc__copy_file()

CGUL_EXPORT void cgul_libc__copy_file	(	cgul_exception_t *	cex,
		FILE *	fin,
		FILE *	fout
	)

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,out]	cex	c-style exception
[in]	fin	input file
[in]	fout	output file

Referenced by cgul_libc_cxx::copy_file().

cgul_libc__ftell()

CGUL_EXPORT long cgul_libc__ftell	(	cgul_exception_t *	cex,
		FILE *	f
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	f	file

Returns

file position

Referenced by cgul_libc_cxx::ftell().

cgul_libc__fseek()

CGUL_EXPORT void cgul_libc__fseek	(	cgul_exception_t *	cex,
		FILE *	f,
		long	offset,
		int	whence
	)

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,out]	cex	c-style exception
[in]	f	file
[in]	offset	offset
[in]	whence	position to which offset is relative

Referenced by cgul_libc_cxx::fseek().

cgul_libc__rewind()

CGUL_EXPORT void cgul_libc__rewind	(	cgul_exception_t *	cex,
		FILE *	f
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	f	file

Referenced by cgul_libc_cxx::rewind().

cgul_libc__fgetpos()

CGUL_EXPORT void cgul_libc__fgetpos	(	cgul_exception_t *	cex,
		FILE *	f,
		fpos_t *	pos
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	f	file
[out]	pos	current file position

Referenced by cgul_libc_cxx::fgetpos().

cgul_libc__fsetpos()

CGUL_EXPORT void cgul_libc__fsetpos	(	cgul_exception_t *	cex,
		FILE *	f,
		fpos_t *	pos
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	f	file
[out]	pos	current file position

Referenced by cgul_libc_cxx::fsetpos().

cgul_libc__tmpfile()

CGUL_EXPORT FILE* cgul_libc__tmpfile

(

cgul_exception_t *

cex

)

Wrapper for tmpfile(). On success, a file opened for reading and writting is returned. On failure, NULL is returned and 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

Parameters

[in,out]

cex

c-style exception

Returns

temporary file

Referenced by cgul_libc_cxx::tmpfile().

cgul_libc__printf()

CGUL_EXPORT int cgul_libc__printf	(	cgul_exception_t *	cex,
		const char *	format,
			...
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	format	format string
[in]	...	variable argument list that matches format

Returns

number of characters read

cgul_libc__vprintf()

CGUL_EXPORT int cgul_libc__vprintf	(	cgul_exception_t *	cex,
		const char *	format,
		va_list	args
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	format	format string
[in]	args	variable argument list that matches format

Returns

number of characters read

Referenced by cgul_libc_cxx::printf(), and cgul_libc_cxx::vprintf().

cgul_libc__fprintf()

CGUL_EXPORT int cgul_libc__fprintf	(	cgul_exception_t *	cex,
		FILE *	f,
		const char *	format,
			...
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	f	output file
[in]	format	format string
[in]	...	variable argument list that matches format

Returns

number of characters read

cgul_libc__vfprintf()

CGUL_EXPORT int cgul_libc__vfprintf	(	cgul_exception_t *	cex,
		FILE *	f,
		const char *	format,
		va_list	args
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	f	output file
[in]	format	format string
[in]	args	variable argument list that matches format

Returns

number of characters read

Referenced by cgul_libc_cxx::fprintf(), and cgul_libc_cxx::vfprintf().

cgul_libc__fgetc()

CGUL_EXPORT int cgul_libc__fgetc	(	cgul_exception_t *	cex,
		FILE *	f
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	f	input file

Returns

character read from f

Referenced by cgul_libc_cxx::fgetc().

cgul_libc__fputc()

CGUL_EXPORT void cgul_libc__fputc	(	cgul_exception_t *	cex,
		int	c,
		FILE *	f
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	c	character to write
[in]	f	output file

Referenced by cgul_libc_cxx::fputc().

cgul_libc__fgets()

CGUL_EXPORT char* cgul_libc__fgets	(	cgul_exception_t *	cex,
		char *	buf,
		int	buf_size,
		FILE *	f
	)

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, NULL is returned and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	buf	buffer where string is stored
[in]	buf_size	size of buf
[in]	f	input file

Returns

buf on success or NULL on EOF or error

Referenced by cgul_libc_cxx::fgets().

cgul_libc__fputs()

CGUL_EXPORT void cgul_libc__fputs	(	cgul_exception_t *	cex,
		const char *	s,
		FILE *	f
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	s	string
[in]	f	file to which s is written

Referenced by cgul_libc_cxx::fputs().

cgul_libc__puts()

CGUL_EXPORT void cgul_libc__puts	(	cgul_exception_t *	cex,
		const char *	s
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	s	string to write

Referenced by cgul_libc_cxx::puts().

cgul_libc__strlen()

CGUL_EXPORT size_t cgul_libc__strlen	(	cgul_exception_t *	cex,
		const char *	s
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	string

Returns

length of s

Referenced by cgul_libc_cxx::strlen().

cgul_libc__strcpy()

CGUL_EXPORT char* cgul_libc__strcpy	(	cgul_exception_t *	cex,
		char *	dst,
		const char *	src
	)

Wrapper for strcpy() to copy src to dst.

Parameters

[in]	cex	c-style exception
[in]	dst	destination string
[in]	src	source string

Returns

dst

Referenced by cgul_libc_cxx::strcpy().

cgul_libc__strncpy()

CGUL_EXPORT char* cgul_libc__strncpy	(	cgul_exception_t *	cex,
		char *	dst,
		const char *	src,
		size_t	dst_size
	)

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

Parameters

[in]	cex	c-style exception
[in]	dst	destination string
[in]	dst_size	size in bytes of dst
[in]	src	source string

Returns

dst

Referenced by cgul_libc_cxx::strncpy().

cgul_libc__strcat()

CGUL_EXPORT char* cgul_libc__strcat	(	cgul_exception_t *	cex,
		char *	dst,
		const char *	src
	)

Wrapper for strcpy() to concatenate src with dst.

Parameters

[in]	cex	c-style exception
[in]	dst	destination string
[in]	src	source string

Returns

dst

Referenced by cgul_libc_cxx::strcat().

cgul_libc__strcmp()

CGUL_EXPORT int cgul_libc__strcmp	(	cgul_exception_t *	cex,
		const char *	s1,
		const char *	s2
	)

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

[in]	cex	c-style exception
	s1	first string to compare
	s2	second string to compare

Returns

result of comparison

Referenced by cgul_libc_cxx::strcmp().

cgul_libc__strdup()

CGUL_EXPORT char* cgul_libc__strdup	(	cgul_exception_t *	cex,
		const char *	s
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	s	string to duplicate

Returns

duplicate string

Referenced by cgul_libc_cxx::strdup().

cgul_libc__snprintf()

CGUL_EXPORT int cgul_libc__snprintf	(	cgul_exception_t *	cex,
		char *	dst,
		long	dst_size,
		const char *	format,
			...
	)

This function is a thin wrapper around cgul_libc__vsnprintf().

Parameters

[in]	cex	c-style exception
[in]	dst	destination string
[in]	dst_size	size of dst
[in]	format	format string
[in]	...	variable length arguments that match format

Returns

length of the string copied to dst

See also

cgul_libc__vsnprintf

cgul_libc__vsnprintf()

CGUL_EXPORT int cgul_libc__vsnprintf	(	cgul_exception_t *	cex,
		char *	dst,
		long	dst_size,
		const char *	format,
		va_list	args
	)

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, -1 is returned and 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]	cex	c-style exception
[in]	dst	destination string
[in]	dst_size	size of dst
[in]	format	format string
[in]	args	variable length arguments that match format

Returns

length of the string copied to dst

See also

cgul_libc__asprintf

Referenced by cgul_libc_cxx::snprintf(), and cgul_libc_cxx::vsnprintf().

cgul_libc__asprintf()

CGUL_EXPORT char* cgul_libc__asprintf	(	cgul_exception_t *	cex,
		const char *	format,
			...
	)

This function is a thin wrapper around cgul_libc__vasprintf().

Parameters

[in,out]	cex	c-style exception
[in]	format	format string
[in]	...	variable arguments that match format

Returns

newly allocated and formatted string

cgul_libc__vasprintf()

CGUL_EXPORT char* cgul_libc__vasprintf	(	cgul_exception_t *	cex,
		const char *	format,
		va_list	args
	)

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 and NULL is returned.

Parameters

[in,out]	cex	c-style exception
[in]	format	format string
[in]	args	variable arguments that match format

Returns

newly allocated and formatted string

Referenced by cgul_libc_cxx::asprintf(), and cgul_libc_cxx::vasprintf().

cgul_libc__basename()

CGUL_EXPORT char* cgul_libc__basename	(	cgul_exception_t *	cex,
		const char *	name
	)

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, NULL is returned, and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	name	name of file

Returns

base name of name

Referenced by cgul_libc_cxx::basename().

cgul_libc__dirname()

CGUL_EXPORT char* cgul_libc__dirname	(	cgul_exception_t *	cex,
		const char *	name
	)

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, NULL is returned, and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	name	name of file

Returns

directory name of name

Referenced by cgul_libc_cxx::dirname().

cgul_libc__extension()

CGUL_EXPORT char* cgul_libc__extension	(	cgul_exception_t *	cex,
		const char *	name
	)

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, NULL is returned, and 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,out]	cex	c-style exception
[in]	name	name of file

Returns

file extension of name

See also

cgul_libc__rootname()

Referenced by cgul_libc_cxx::extension().

cgul_libc__rootname()

CGUL_EXPORT char* cgul_libc__rootname	(	cgul_exception_t *	cex,
		const char *	name
	)

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, NULL is returned, and 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/" in this case (because of the path separator).

Parameters

[in,out]	cex	c-style exception
[in]	name	name of file

Returns

root name of name

Referenced by cgul_libc_cxx::rootname().

cgul_libc__strip_utf8_byte_order_mark()

CGUL_EXPORT int cgul_libc__strip_utf8_byte_order_mark	(	cgul_exception_t *	cex,
		FILE *	f
	)

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, 0 is returned, and 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,out]	cex	c-style exception
[in]	f	file

Returns

whether the utf8 byte order mark was stripped

Referenced by cgul_libc_cxx::strip_utf8_byte_order_mark().