Basics

Description

Some very basic definitions and functions.

Collaboration diagram for Basics:

Macros
#define	MIN(A, B)   ((A) < (B) ? (A) : (B))
	Typeless min-operator.
#define	MAX(A, B)   ((A) > (B) ? (A) : (B))
	Typeless max-operator.
#define	STR(X)   #X
	Stringify macro.
#define	OFFSET(type, field)   ((unsigned) &(((type *) 0)->field))
	Byte offset of a field in struct or class.
#define	ENTRIES(ARRAY)   ((int) (sizeof (ARRAY) / sizeof (ARRAY[0])))
	Number of entries of a statically declared constant array.
#define	CLEAR(X)   bzero (&(X), sizeof (X))
	Set variable/object 'X' to all-zero.

Enhanced file and directory operations ...
size_t	Write (int fd, const void *buf, size_t count)
	Similar to POSIX write(), but writes all 'count' bytes as possible. More...
size_t	Read (int fd, void *buf, size_t count)
	Similar to POSIX read(), but reads all 'count' bytes as possible. More...
bool	MakeDir (const char *relOrAbsPath, bool setHome2lGroup=true)
	Create a directory (and all its parents as necessary). More...
bool	UnlinkTree (const char *relOrAbsPath, const char *skipPattern=NULL)
	Unlink (remove) a directory with all its decendants. More...
bool	ReadDir (const char *relOrAbsPath, class CKeySet *ret)
	Read a directory into a CKeySet object. More...

Atomic read and write operations ...
(presently GCC-specific)
#define	ATOMIC_READ(OBJ)   __atomic_load_n (&(OBJ), __ATOMIC_RELAXED)
#define	ATOMIC_WRITE(OBJ, VAL)   __atomic_store_n (&(OBJ), VAL, __ATOMIC_RELAXED)
#define	ATOMIC_INC(OBJ, N)   __atomic_exchange_n (&(OBJ), (OBJ) + (N), __ATOMIC_RELAXED)

Function Documentation

Write()

size_t Write	(	int	fd,
		const void *	buf,
		size_t	count
	)

Similar to POSIX write(), but writes all 'count' bytes as possible.

This function repeatedly calls write(2) until 'count' bytes have been written. On error, the actual number of bytes written is returned (which is less than 'count'), and 'errno' is set accordingly. If the file is opened in non-blocking mode, the function does not wait, but writes as many bytes as possible immediately and sets/leaves 'errno == EAGAIN'.

Returns

the number of bytes written successfully.

Read()

size_t Read	(	int	fd,
		void *	buf,
		size_t	count
	)

Similar to POSIX read(), but reads all 'count' bytes as possible.

This function repeatedly calls read(2) until 'count' bytes have been read. On error or end-of-file, the actual number of bytes read is returned (which is less than 'count'), and 'errno' is set accordingly. In the case of an end-of-file condition, 'errno' is set to 0. If the file is opened in non-blocking mode, the function does not wait, but returns the bytes available immediately and sets/leaves 'errno == EAGAIN'.

Returns

the number of bytes read successfully.

MakeDir()

bool MakeDir	(	const char *	relOrAbsPath,
		bool	setHome2lGroup = true
	)

Create a directory (and all its parents as necessary).

If the argument is a symbolic links, the target directory (tree) is created if it does not yet exist.

Parameters

relOrAbsPath	is either an absolute path or a path relative to HOME2L_ROOT and must identify a directory.
setHome2lGroup	selects to set the directory group ownerships to HOME2L_USER, if possible.

Returns

success status (on error, a warning is logged).

UnlinkTree()

bool UnlinkTree	(	const char *	relOrAbsPath,
		const char *	skipPattern = NULL
	)

Unlink (remove) a directory with all its decendants.

Parameters

relOrAbsPath	is either an absolute path or a path relative to HOME2L_ROOT and must identify a directory.
skipPattern	identifies portions not to be unlinked. Presently, only a whitespace-separated list of items of the form "\<name\>" is supported, which means that, if relOrAbsPath is a directory, its top-level directory <name> is skipped. Further variants may be implemented in the future.

Returns

success status (on error, a warning is logged).

ReadDir()

bool ReadDir	(	const char *	relOrAbsPath,
		class CKeySet *	ret
	)

Read a directory into a CKeySet object.

Parameters

relOrAbsPath	is either an absolute path or a path relative to $PWD
ret	points to the CKeySet object to be filled

Returns

success status (on error, a warning is logged).

In case of an error, the contents of 'ret' are unspecified.