Miscellaneous convenience functions

Typedefs
typedef _GGZFile	GGZFile
	Structure used internally by ggz_read_line().
Functions
char *	ggz_xml_escape (const char *str)
	Escape XML characters in a text string.
char *	ggz_xml_unescape (const char *str)
	Restore escaped XML characters into a text string.
GGZFile *	ggz_get_file_struct (int fdes)
	Setup a file structure to use with ggz_read_line().
int	ggz_make_path (const char *full)
	Create directories to fill out a path.
char *	ggz_read_line (GGZFile *file)
	Read a line of arbitrary length from a file.
void	ggz_free_file_struct (GGZFile *file)
	Deallocate a file structure allocated via ggz_get_file_struct().
int	ggz_strcmp (const char *s1, const char *s2)
	String comparison function that is safe with NULLs.
int	ggz_strcasecmp (const char *s1, const char *s2)
	Case-insensitive string comparison function that is safe with NULLs The function returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

---

Function Documentation

char* ggz_xml_escape

(

const char *

str

)

Escape XML characters in a text string.

Parameters:

str

The string to encode

Returns:

A pointer to a dynamically allocated string with XML characters replaced with ampersand tags, or NULL on error

Note:

The dynamic memory is allocated using ggz_malloc() and the caller is expected to later free this memory using ggz_free(). If the original string did not contain any characters which required escaping a ggz_strdup() copy is returned.

char* ggz_xml_unescape

(

const char *

str

)

Restore escaped XML characters into a text string.

Parameters:

str

The string to decode

Returns:

A pointer to a dynamically allocated string with XML ampersand tags replaced with their normal ASCII characters, or NULL on error

Note:

The dyanmic memory is allocated using ggz_malloc() and the caller is expected to later free this memory using ggz_free(). If the original string did not contain any characters which required decoding, a ggz_strdup() copy is returned.

When using expat, incoming text is automatically unescaped by the expat library. It is therefore generally not necessary to use this function with expat.

GGZFile* ggz_get_file_struct

(

int

fdes

)

Setup a file structure to use with ggz_read_line().

Parameters:

fdes

A preopened integer file descriptor to read from

Returns:

A pointer to a dynamically allocated GGZFile structure

Note:

The user MUST have opened the requested file for reading before using this function. When finished using ggz_read_line(), the user should cleanup this struct using ggz_free_file_struct().

int ggz_make_path

(

const char *

full

)

Create directories to fill out a path.

New directories are created with permissions 700 (S_IRWXU).

Parameters:

full

The full path to be created.

Returns:

0 on success; -1 on failure

char* ggz_read_line

(

GGZFile *

file

)

Read a line of arbitrary length from a file.

Parameters:

file

A GGZFile structure allocated via ggz_get_file_struct()

Returns:

A NULL terminated line from the file of arbitrary length or NULL at end of file

Note:

The dynamic memory is allocated using ggz_malloc() and the caller is expected to later free this memory using ggz_free().

void ggz_free_file_struct

(

GGZFile *

file

)

Deallocate a file structure allocated via ggz_get_file_struct().

Parameters:

file

A GGZFile structure allocated via ggz_get_file_struct()

Note:

The caller is expected to close the I/O file before or after freeing the file structure.

int ggz_strcmp	(	const char *	s1,
		const char *	s2
	)

String comparison function that is safe with NULLs.

Parameters:

	s1	First string to compare
	s2	Second string to compare

Returns:

An integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2

Note:

NULL in considered to be less than any non-NULL string and equal to itself

int ggz_strcasecmp	(	const char *	s1,
		const char *	s2
	)

Case-insensitive string comparison function that is safe with NULLs The function returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.

NULL in considered to be less than any non-NULL string and equal to itself

Parameters:

	s1	First string to compare
	s2	Second string to compare

Returns:

The comparison value.

---