Miscellaneous library functions

Detailed Description

This header file contains functions that are used by the web-server.

The functions might also be useful for the code you design. Some of the functions are replacements for functions in the C Standard Library.

See also

Barracuda Introduction

Classes
struct	BaTm
	Represents the components of calendar time. More...
struct	BaTimeEx
	UTC timestamp with a fractional second and an explicit timezone offset. More...

Typedefs
typedef int8_t	S8
	Signed 8-bit integer. More...
typedef int16_t	S16
	Signed 16-bit integer. More...
typedef int32_t	S32
	Signed 32-bit integer. More...
typedef int64_t	S64
	Signed 64-bit integer. More...
typedef uint8_t	U8
	Unsigned 8-bit integer. More...
typedef uint16_t	U16
	Unsigned 16-bit integer. More...
typedef uint32_t	U32
	Unsigned 32-bit integer. More...
typedef uint64_t	U64
	Unsigned 64-bit integer. More...
typedef S64	BaTime
	An arithmetic type representing calendar time with epoch of 1970-01-01 00:00:00 UTC, that is, +/- number of seconds since the epoch of 1970-01-01. More...
typedef U8	BaBool
	Boolean stored in an unsigned byte; FALSE is zero and TRUE is one. More...
typedef U32	BaFileSize
	Unsigned file size or position in bytes; 32 bits without BA_FILESIZE64. More...
typedef S32	SBaFileSize
	Signed file-size value in bytes; 32 bits without BA_FILESIZE64. More...

Functions
BA_API void	baConvBin2Hex (void *hexOutData, U8 binIn)
	Encode one byte as two lowercase hexadecimal characters. More...
BA_API U8	baConvHex2Bin (U8 c)
	Decode one hexadecimal digit. More...
BA_API void	baConvU32ToHex (void *to, U32 from)
	Encode four bytes as eight lowercase hexadecimal characters. More...
BA_API U32	baConvHexToU32 (const void *from)
	Decode eight hexadecimal characters into a U32. More...
BA_API char *	baStrdup (const char *str)
	Allocate a NUL-terminated copy of a string using baMalloc. More...
BA_API const void *	baBSearch (const void *key, const void *base, int num, int size, int(*cmp)(const void *, const void *))
	Find a key in a sorted array without modifying it. More...
BA_API int	baStrCaseCmp (const char *a, const char *b)
	Compare two NUL-terminated strings using bTolower for case folding. More...
BA_API int	baStrnCaseCmp (const char *a, const char *b, size_t len)
	Compare at most len bytes, using bTolower for case folding. More...
const char *	baGetToken (const char **str, const char *set)
	Locate a token separated by characters in set. More...
BA_API BaTime	baParseDate (const char *str)
	Parse an HTTP date string as UTC. More...
BA_API int	baB64Decode (unsigned char *outStr, int outStrSize, const char *b64EncStr, BaBool *overflow)
	Decode base64 or base64url into a caller buffer. More...
BA_API int	baElideDotDot (char *str)
	Normalize a slash-separated path in place. More...
BA_API void	baXmlUnescape (char *f)
	Decode selected XML entity spellings in place. More...
BA_API U8	baDaysInMonth (U16 y, U16 m)
	Return the number of days in a Gregorian calendar month. More...
BA_API int	baTime2tm (struct BaTm *tmP, BaTime t)
	Convert UTC epoch seconds to calendar fields. More...
BA_API int	baTime2tmEx (const BaTimeEx *tex, const BaBool local, struct BaTm *tm)
	Convert a timestamp to UTC or offset-adjusted calendar fields. More...
BA_API BaTime	baTm2Time (struct BaTm *tmP)
	Convert calendar fields to UTC epoch seconds. More...
BA_API int	baTm2TimeEx (struct BaTm *tm, BaBool local, BaTimeEx *tex)
	Convert calendar fields and an optional timezone offset to a timestamp. More...
BA_API int	baISO8601ToTime (const char *str, size_t len, BaTimeEx *tex)
	Parse an ISO 8601 calendar timestamp with an explicit timezone. More...
BA_API int	baTime2ISO8601 (const BaTimeEx *tex, char *str, size_t len)
	Format a timestamp as ISO 8601 using its timezone offset. More...

Typedef Documentation

BaBool

typedef U8 BaBool

Boolean stored in an unsigned byte; FALSE is zero and TRUE is one.

BaFileSize

typedef U32 BaFileSize

Unsigned file size or position in bytes; 32 bits without BA_FILESIZE64.

BaTime

typedef S64 BaTime

An arithmetic type representing calendar time with epoch of 1970-01-01 00:00:00 UTC, that is, +/- number of seconds since the epoch of 1970-01-01.

See also

baTime2tm

baTm2Time

S16

typedef int16_t S16

Signed 16-bit integer.

S32

typedef int32_t S32

Signed 32-bit integer.

S64

typedef int64_t S64

Signed 64-bit integer.

S8

typedef int8_t S8

Signed 8-bit integer.

SBaFileSize

typedef S32 SBaFileSize

Signed file-size value in bytes; 32 bits without BA_FILESIZE64.

U16

typedef uint16_t U16

Unsigned 16-bit integer.

U32

typedef uint32_t U32

Unsigned 32-bit integer.

U64

typedef uint64_t U64

Unsigned 64-bit integer.

U8

typedef uint8_t U8

Unsigned 8-bit integer.

Function Documentation

baB64Decode()

BA_API int baB64Decode	(	unsigned char *	outStr,
		int	outStrSize,
		const char *	b64EncStr,
		BaBool *	overflow
	)

Decode base64 or base64url into a caller buffer.

Parameters

[out]	outStr	Buffer with outStrSize writable bytes; it may alias b64EncStr for in-place decoding. No NUL terminator is written.
[in]	outStrSize	Nonnegative capacity in bytes.
[in]	b64EncStr	Required NUL-terminated input. Bytes outside both base64 alphabets, including padding, are ignored rather than rejected.
[out]	overflow	Optional pointer, set to TRUE if decoded bytes were discarded because the output was full; otherwise FALSE. May be NULL.

Returns

Number of bytes actually written, not the full decoded length. Invalid input is not reported separately.

baBSearch()

BA_API const void * baBSearch	(	const void *	key,
		const void *	base,
		int	num,
		int	size,
		int(*)(const void *, const void *)	cmp
	)

Find a key in a sorted array without modifying it.

Parameters

[in]	key	Search key passed as the comparator's first argument.
[in]	base	Array of num records sorted in ascending comparator order.
[in]	num	Nonnegative number of records.
[in]	size	Positive size of each record in bytes. Array indexing and midpoint arithmetic must fit in int as used by this implementation.
[in]	cmp	Required comparison callback, called as cmp(key, record). It returns negative, zero or positive when key is less than, equal to or greater than the record's key. It must not reorder the array.

Returns

Borrowed pointer to a matching record, or NULL if no match exists or num is zero. With duplicate keys, which record is returned is unspecified.

baConvBin2Hex()

BA_API void baConvBin2Hex	(	void *	hexOutData,
		U8	binIn
	)

Encode one byte as two lowercase hexadecimal characters.

Parameters

[out]	hexOutData	Writable buffer of at least two bytes. No NUL is added.
[in]	binIn	Byte to encode.

baConvHex2Bin()

BA_API U8 baConvHex2Bin

(

U8

c

)

Decode one hexadecimal digit.

Parameters

[in]

c

Character from 0-9, a-f or A-F.

Returns

Numeric value 0-15; an invalid character also returns zero.

baConvHexToU32()

BA_API U32 baConvHexToU32

(

const void *

from

)

Decode eight hexadecimal characters into a U32.

Parameters

[in]

from

At least eight readable characters, or NULL. A terminator is not read. Invalid characters decode as zero-valued nibbles.

Returns

Decoded value, or zero for NULL. Byte placement is the inverse of baConvU32ToHex and therefore depends on the target byte order.

baConvU32ToHex()

BA_API void baConvU32ToHex	(	void *	to,
		U32	from
	)

Encode four bytes as eight lowercase hexadecimal characters.

Parameters

[out]	to	Writable buffer of at least eight bytes; no NUL is added.
[in]	from	Value to encode. The implementation visits its memory bytes from offset 3 to offset 0, producing conventional most-significant-digit first notation on little-endian targets. See baConvHexToU32.

baDaysInMonth()

BA_API U8 baDaysInMonth	(	U16	y,
		U16	m
	)

Return the number of days in a Gregorian calendar month.

Parameters

[in]	y	Calendar year used for leap-year calculation.
[in]	m	Month from 1 (January) through 12 (December); not validated.

Returns

Number of days, from 28 through 31.

baElideDotDot()

BA_API int baElideDotDot

(

char *

str

)

Normalize a slash-separated path in place.

Parameters

[in,out]

str

Required writable NUL-terminated path. Repeated slashes, '.' components and matched parent components are removed without allocation.

Returns

Zero on completion, -1 if a parent component would escape the starting level. The buffer may have been modified on failure. This function does not resolve filesystem links or perform filesystem access checks.

baGetToken()

const char * baGetToken	(	const char **	str,
		const char *	set
	)

Locate a token separated by characters in set.

Parameters

[in,out]	str	Required pointer to a nonempty NUL-terminated string. Leading delimiter characters are skipped by advancing *str. On success *str points to the first token byte; the function does not advance it to the returned end pointer. The string itself is not modified.
[in]	set	NUL-terminated delimiter character set.

Returns

Borrowed pointer just past the token, at a delimiter or the NUL, or NULL when only delimiters remain. The token is not NUL-terminated by this function; its length is the returned pointer minus *str.

baISO8601ToTime()

BA_API int baISO8601ToTime	(	const char *	str,
		size_t	len,
		BaTimeEx *	tex
	)

Parse an ISO 8601 calendar timestamp with an explicit timezone.

Parameters

[in]	str	Required readable input, with format YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS+HH:MM (also allowing a negative offset). A space or lowercase t may replace T; lowercase z is accepted. An optional decimal point and 1..9 fractional digits may precede the timezone.
[in]	len	Exact byte length, excluding any NUL; at least 20. Supply a complete timezone suffix. No trailing characters are accepted.
[out]	tex	Required timestamp buffer, valid only on success. sec is UTC, nsec is scaled to nanoseconds, and offset retains the supplied minutes.

Returns

Zero on success, -1 for a detected invalid format or date. Years are 0001..9999; leap seconds and a missing timezone are not supported.

baParseDate()

BA_API BaTime baParseDate

(

const char *

str

)

Parse an HTTP date string as UTC.

Parameters

[in]

str

NUL-terminated IMF-fixdate, RFC 850, or asctime date, or NULL. Names are case-sensitive; the first two forms require GMT. Surrounding SP/HTAB is accepted; invalid calendar fields, trailing data, and date lists are rejected. RFC 850 years use the HTTP 50-year rule and the server clock. A recognized weekday name is required but is not compared to the date.

Returns

Seconds since 1970-01-01 00:00:00 UTC, or zero for invalid, NULL, or empty input. Zero is also a valid timestamp. A leap second (60) maps to the following POSIX second; no historical leap-second table is consulted.

See also

BaTime

baStrCaseCmp()

BA_API int baStrCaseCmp	(	const char *	a,
		const char *	b
	)

Compare two NUL-terminated strings using bTolower for case folding.

Parameters

[in]	a	Required first string.
[in]	b	Required second string. This is a byte comparison, not Unicode case folding; character handling follows the platform bTolower definition.

Returns

Negative, zero or positive when a sorts before, equals or sorts after b under that comparison.

baStrdup()

BA_API char * baStrdup

(

const char *

str

)

Allocate a NUL-terminated copy of a string using baMalloc.

Parameters

[in]

str

Source string or NULL; the source is not modified.

Returns

Owned copy including a NUL byte, or NULL for a NULL source or an allocation failure. Release a successful result with baFree.

baStrnCaseCmp()

BA_API int baStrnCaseCmp	(	const char *	a,
		const char *	b,
		size_t	len
	)

Compare at most len bytes, using bTolower for case folding.

Parameters

[in]	a	First string, readable through its NUL or len bytes.
[in]	b	Second string, readable through its NUL or len bytes.
[in]	len	Maximum byte count; zero performs no character access.

Returns

Negative, zero or positive as in baStrCaseCmp. Equal prefixes of len bytes compare equal even if the strings differ afterward.

baTime2ISO8601()

BA_API int baTime2ISO8601	(	const BaTimeEx *	tex,
		char *	str,
		size_t	len
	)

Format a timestamp as ISO 8601 using its timezone offset.

Parameters

[in]	tex	Required timestamp satisfying baTime2tmEx requirements.
[out]	str	Writable output buffer; NUL-terminated on success. The output uses T, a nine-digit fractional part when nsec is nonzero, and Z for offset zero or a signed HH:MM offset otherwise.
[in]	len	Buffer capacity in bytes, including the NUL. At least 36 bytes are required even when the particular result would be shorter.

Returns

Character count excluding the NUL, or -1 for insufficient capacity or an invalid timestamp. Output is valid only on success.

baTime2tm()

BA_API int baTime2tm	(	struct BaTm *	tmP,
		BaTime	t
	)

Convert UTC epoch seconds to calendar fields.

Parameters

[out]	tmP	Required output structure; valid only on success. tm_year is years since 1900, tm_mon is zero-based, nsec and offset are zero.
[in]	t	UTC seconds from -62135596800 through 253402300799 (years 0001 through 9999).

Returns

Zero on success, -1 for a timestamp outside the supported range.

baTime2tmEx()

BA_API int baTime2tmEx	(	const BaTimeEx *	tex,
		const BaBool	local,
		struct BaTm *	tm
	)

Convert a timestamp to UTC or offset-adjusted calendar fields.

Parameters

[in]	tex	Required timestamp. nsec must be 0-999999999 and offset must be -1439..1439 minutes. sec + offset * 60 must fall in years 0001..9999; callers must also keep the calendar value selected by local in that range.
[in]	local	TRUE applies tex->offset; FALSE produces UTC fields.
[out]	tm	Required output, valid only on success. tm_year is the full calendar year, tm_mon is zero-based. nsec and offset are copied even when local is FALSE. Weekday and year-day fields are populated.

Returns

Zero on success, -1 when timestamp validation fails.

baTm2Time()

BA_API BaTime baTm2Time

(

struct BaTm *

tmP

)

Convert calendar fields to UTC epoch seconds.

Parameters

[in,out]

tmP

Required structure with tm_year as years since 1900, tm_mon in 0..11 and valid day/time fields. Initialize nsec and offset to zero. The function changes tm_year and tm_mon, including on failure; pass a copy if the original fields are needed afterward. tm_wday and tm_yday are ignored.

Returns

Epoch seconds on success, or zero for a reported calendar error. Zero is also a valid result; use baTm2TimeEx for a separate status value.

baTm2TimeEx()

BA_API int baTm2TimeEx	(	struct BaTm *	tm,
		BaBool	local,
		BaTimeEx *	tex
	)

Convert calendar fields and an optional timezone offset to a timestamp.

Parameters

[in,out]	tm	Required initialized structure. tm_year is the full year (use 1..9999), tm_mon is 0..11, and day, hour, minute and second must form a valid date/time. Supply valid nsec and offset values as described by BaTimeEx; these two fields are copied without validation. tm_wday and tm_yday are ignored. tm_mon and possibly tm_year are changed during conversion, including on failure; use a copy to preserve the input.
[in]	local	TRUE subtracts tm->offset to obtain UTC seconds; FALSE interprets the calendar fields as UTC.
[out]	tex	Required output timestamp, valid only on success.

Returns

Zero on success, -1 for a detected invalid date/time.

baXmlUnescape()

BA_API void baXmlUnescape

(

char *

f

)

Decode selected XML entity spellings in place.

Parameters

[in,out]

f

Required writable NUL-terminated string. The result remains NUL-terminated and is no longer than the input. Numeric character references and unrecognized entity spellings remain unchanged. The implementation handles lt, gt, apos and amp, but currently spells the quote entity as "qout" rather than the XML spelling "quot". No error status is returned.