Home2L - C/C++ API  v1.2-2-ga4fe (2023-04-15)
Smart Tools for a Private Home
Macros
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
relOrAbsPathis either an absolute path or a path relative to HOME2L_ROOT and must identify a directory.
setHome2lGroupselects 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
relOrAbsPathis either an absolute path or a path relative to HOME2L_ROOT and must identify a directory.
skipPatternidentifies 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
relOrAbsPathis either an absolute path or a path relative to $PWD
retpoints 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.