Miscellaneous Utility Functions

Overview

Functions
int	u_asctime_to_tt (const char str, time_t tp)
	Convert an asctime(3) string to `time_t`.
int	u_rfc850_to_tt (const char str, time_t tp)
	Convert an rfc850 time string to `time_t`.
int	u_rfc822_to_tt (const char str, time_t tp)
	Convert an rfc822 time string to `time_t`.
int	u_httpdate_to_tt (const char str, time_t tp)
	Convert an HTTP time string to `time_t`.
int	u_tt_to_rfc822 (char dst[RFC822_DATE_BUFSZ], time_t ts)
	Convert a `time_t` value to a rfc822 time string.
char *	u_strnstr (const char buf, const char sub, size_t buflen)
	Locate a substring in another string.
int	u_foreach_dir_item (const char path, unsigned int mask, int(cb)(struct dirent , const char , void ), void arg)
	Apply the supplied callback to each file in a given directory.
int	u_match_ext (const char filename, const char extension)
	Match filename extension.
ssize_t	u_sqlncpy (char d, const char s, size_t slen, int flags)
	Copy and SQL escape/unescape a given string.
ssize_t	u_urlncpy (char d, const char s, size_t slen, int flags)
	Copy and URL escape/unescape a given string.
ssize_t	u_hexncpy (char d, const char s, size_t slen, int flags)
	Copy and HEX encode/decode a given string.
ssize_t	u_htmlncpy (char d, const char s, size_t slen, int flags)
	Copy and HTML escape/unescape a given string.
char *	u_stristr (const char string, const char sub)
	Locate a given substring ignoring case.
char *	u_strnrchr (const char *s, char c, size_t len)
	Locate a character in a string.
int	u_tmpfile_open (const char tmpdir, io_t *pio)
	Create a temporary `io_t` object.
int	u_file_open (const char file, int flags, io_t *pio)
	Create an `io_t` object from the file system object `file`.
int	u_getline (io_t io, u_string_t ln)
	Read a line from the `io_t` object `io`.
int	u_fgetline (FILE in, u_string_t ln)
	get a line from a `FILE` object
int	u_file_exists (const char *fqn)
	Tell if the given file exists.
void	u_tohex (char hex, const char src, size_t sz)
	Convert a given string in hexadecimal representation.
int	u_md5 (const char *buf, size_t sz, char out[MD5_DIGEST_BUFSZ])
	Calculate the MD5 digest over a given buffer.
int	u_md5io (io_t *io, char out[MD5_DIGEST_BUFSZ])
	Calculate the MD5 hash over an `io_t` stream.
const mime_map_t *	u_get_mime_map (const char *file_name)
	Get the MIME type of a file.
const char *	u_guess_mime_type (const char *file_name)
	Guess the MIME type of a file.
const char *	klone_version (void)
	Return KLone version string (x.y.z).

Function Documentation

int u_asctime_to_tt	(	const char *	str,
		time_t *	tp
	)

Convert the asctime(3) string str to its time_t representation tp.

Parameters:

	str	the string to be converted
	tp	the `time_t` conversion of `str` as a value-result argument

Returns:

0 successful
~0 failure

Definition at line 63 of file date.c.

Referenced by u_httpdate_to_tt().

int u_rfc850_to_tt	(	const char *	str,
		time_t *	tp
	)

Convert the rfc850 string str to its time_t representation tp.

Parameters:

	str	the string to be converted
	tp	the `time_t` conversion of `str` as a value-result argument

Returns:

0 successful
~0 failure

Definition at line 109 of file date.c.

Referenced by u_httpdate_to_tt().

int u_rfc822_to_tt	(	const char *	str,
		time_t *	tp
	)

Convert the rfc822 string str to its time_t representation tp.

Parameters:

	str	the string to be converted
	tp	the `time_t` conversion of `str` as a value-result argument

Returns:

0 successful
~0 failure

Definition at line 161 of file date.c.

Referenced by u_httpdate_to_tt().

int u_httpdate_to_tt	(	const char *	str,
		time_t *	tp
	)

Convert the HTTP time string str to its time_t representation tp.

Parameters:

	str	the string to be converted
	tp	the `time_t` conversion of `str` as a value-result argument

Returns:

0 successful
~0 failure

Definition at line 211 of file date.c.

References u_asctime_to_tt(), u_rfc822_to_tt(), and u_rfc850_to_tt().

int u_tt_to_rfc822	(	char	dst[RFC822_DATE_BUFSZ],
		time_t	ts
	)

Convert the time_t value ts to a rfc822 time string

Parameters:

	dst	placeholder for the rfc822 time string. The buffer, of at least RFC822_DATE_BUFSZ bytes, must be preallocated by the caller.
	ts	the `time_t` value to be converted

Returns:

0 successful
~0 failure

Definition at line 239 of file date.c.

Referenced by response_set_cookie(), response_set_date(), and response_set_last_modified().

char* u_strnstr	(	const char *	buf,
		const char *	sub,
		size_t	buflen
	)

The function locates the first occurrence of sub in the string buf of size buflen

Parameters:

	buf
	sub
	buflen

Returns:

0 successful
~0 error

Definition at line 198 of file utils.c.

int u_foreach_dir_item	(	const char *	path,
		unsigned int	mask,
		int()(struct dirent , const char , void )	cb,
		void *	arg
	)

Apply the supplied callback cb with additional arguments arg to each file in directory path which match the given mask.

Parameters:

	path	directory path
	mask	matching file mask
	cb	function to call
	arg	optional additional arguments

Returns:

0 successful
~0 error

Definition at line 238 of file utils.c.

int u_match_ext	(	const char *	filename,
		const char *	extension
	)

Return 1 if the filename externsion is equal to extension (case-insensitive comparison).

Parameters:

	filename	file name
	extension	file extension to match

Returns:

1 if filename extension is extension
0 if filename extension is not equal to extension

Definition at line 291 of file utils.c.

ssize_t u_sqlncpy	(	char *	d,
		const char *	s,
		size_t	slen,
		int	flags
	)

Copy and SQL escape/unescape, depending on flags value, the string s into d. The destination string, which must be at least slen + 1 bytes long, is NULL terminated.

Parameters:

	d	the encoded/decoded string
	s	string to process
	slen	length of `s`
	flags	one of `SQLCPY_ENCODE` or `SQLCPY_DECODE`

Returns:: The number of characters written to d not including the trailing '\0' or -1 on error.

Definition at line 397 of file utils.c.

ssize_t u_urlncpy	(	char *	d,
		const char *	s,
		size_t	slen,
		int	flags
	)

Copy an URL escaped/unescaped version of string s, depending on flags value, into d. The destination string is NULL terminated. The destination string d must be at least slen + 1 bytes long.

Parameters:

	d	the encoded/decoded string
	s	string to process
	slen	length of `s`
	flags	one of `URLCPY_ENCODE` or `URLCPY_DECODE`

Returns:: The number of characters written to d not including the trailing '\0' or -1 on error.

Definition at line 495 of file utils.c.

Referenced by response_set_cookie().

ssize_t u_hexncpy	(	char *	d,
		const char *	s,
		size_t	slen,
		int	flags
	)

Copy an HEX encoded/decoded version of string s, depending on flags value, into d. The destination string d, which must be at least slen + 1 bytes long, is NULL terminated.

Parameters:

	d	the encoded/decoded string
	s	string to process
	slen	length of `s`
	flags	one of `HEXCPY_ENCODE` or `HEXCPY_DECODE`

Returns:: The number of characters written to d not including the trailing '\0' or -1 on error.

Definition at line 598 of file utils.c.

ssize_t u_htmlncpy	(	char *	d,
		const char *	s,
		size_t	slen,
		int	flags
	)

Copy an HTML escaped/unescaped version of string s, depending on flags value, into d. The destination string is NULL terminated. The destination string d must be at least slen + 1 bytes long.

Parameters:

	d	the encoded/decoded string
	s	string to process
	slen	length of `s`
	flags	one of `HTMLCPY_ENCODE` or `HTMLCPY_DECODE`

Returns:: The number of characters written to d not including the trailing '\0' or -1 on error.

Definition at line 694 of file utils.c.

char* u_stristr	(	const char *	string,
		const char *	sub
	)

Locate the first occurrence of the null-terminated string sub in the null-terminated string string, ignoring the case of both string.

Parameters:

	string	string to be searched
	sub	substring to search

Returns:: the pointer to the found substring or NULL if sub occurs nowhere in string

Definition at line 726 of file utils.c.

char* u_strnrchr	(	const char *	s,
		char	c,
		size_t	len
	)

Locate the last occurrence of c in the substring of length len starting at s.

Parameters:

	s	pointer to the starting of the string
	c	the character to search
	len	length of the string to be searched

Returns:: the pointer to the character, or NULL if c doesn't occur in s

Definition at line 758 of file utils.c.

int u_tmpfile_open	(	const char *	tmpdir,
		io_t **	pio
	)

Create a temporary io_t object at *pio.

Parameters:

	tmpdir	optional base temp directory, supply `NULL` to use the default value
	pio	pointer to the temporary `io_t` object

Returns:

0 successful
~0 error

Definition at line 785 of file utils.c.

References io_name_set().

int u_file_open	(	const char *	file,
		int	flags,
		io_t **	pio
	)

Create an io_t object at *pio from the file system object file. The file is opened with the permission bits given in mode.

Parameters:

	file	pathname of the file to open
	flags	permission bits passed to the open syscall
	pio	the `io_t` object associated to `file`

Returns:

0 successful
~0 error

Definition at line 847 of file utils.c.

References io_name_set().

int u_getline	(	io_t *	io,
		u_string_t *	ln
	)

Read a line and place it into ln from the io_t object io

Parameters:

	io	an initialised `io_t` object
	ln	the line read

Returns:

0 successful
~0 error

Definition at line 889 of file utils.c.

References io_gets().

int u_fgetline	(	FILE *	in,
		u_string_t *	ln
	)

Try to get a line from the FILE object in and store it at ln.

Parameters:

	in	the `FILE` object from which read is performed
	ln	the `u_string_t` object where the line read is stored

Returns:

0 successful
~0 error

Definition at line 928 of file utils.c.

int u_file_exists ( const char * fqn )

Tell if the given file fqn exists

Parameters:

fqn

the path of the (regular) file to check

Returns:: 1 if the file exists and is a regular file, 0 otherwise

Definition at line 1013 of file utils.c.

void u_tohex	(	char *	hex,
		const char *	src,
		size_t	sz
	)

Convert the string src of lenght sz into its hexadecimal representation hex. The string hex must be at least 2 * sz long.

Parameters:

	hex	the string holding the hexadecimal conversion of `src`
	src	the string that has to be converted
	sz	the length of `src`

Returns:: nothing

Definition at line 1036 of file utils.c.

Referenced by u_md5(), and u_md5io().

int u_md5	(	const char *	buf,
		size_t	sz,
		char	out[MD5_DIGEST_BUFSZ]
	)

Calculate the MD5 digest over the supplied buffer buf of size sz and place it at out.

Parameters:

	buf	the buffer to be hashed
	sz	length in bytes of `buf`
	out	hexadecimal string containing the MD5 hash calculated over `buf`. It must be at least `MD5_DIGEST_BUFSZ` bytes long.

Returns:

0 always successful

Definition at line 1067 of file utils.c.

References u_tohex().

int u_md5io	(	io_t *	io,
		char	out[MD5_DIGEST_BUFSZ]
	)

Calculate the MD5 hash over an io_t stream io and place the result as an hexadecimal string into out.

Parameters:

	io	the `io_t` stream to be hashed
	out	hexadecimal string containing the MD5 hash calculated over `buf`. It must be at least `MD5_DIGEST_BUFSZ` bytes long.

Returns:

0 successful
~0 error

Definition at line 1100 of file utils.c.

References io_read(), and u_tohex().

const mime_map_t* u_get_mime_map ( const char * file_name )

Get the MIME type of the given file file_name by its extension

Parameters:

file_name

the path of the file

Returns:: the found MIME map, or the first map if no match could be found

Definition at line 1162 of file utils.c.

const char* u_guess_mime_type ( const char * file_name )

Guess the MIME type of the given file file_name by its extension

Parameters:

file_name

the path of the file

Returns:: the string corresponding to the guessed MIME type, or "application/octet-stream" in case no map could be found

Definition at line 1195 of file utils.c.

const char* klone_version ( void )

Return KLone version string in the format x.y.z.

Returns:: the version string

Definition at line 30 of file version.c.