Symisc Systems

Libcox API Reference - List of Objects

Star Follow @symisc

This is a list of all abstract objects and datatypes used by Libcox. There are 7 exported objects in total, but the two most important is: A libcox handle libcox and an object value represented by libcox_value.









Libcox Handle

typedef struct libcox libcox;

Each active handle is represented by a pointer to an instance of the opaque structure named libcox. It is useful to think of an libcox pointer as an object. The libcox_init() is its constructor, libcox_release() is its destructor and libcox_exec() is the main processing interface. Most of exported interfaces such as libcox_exec_fmt(), libcox_register_command(), etc. expect a pointer to an instance of this structure as their first arguments.

Libcox Object Value

typedef struct libcox_value libcox_value;

Libcox uses the libcox_value object to represent all values that can be returned from an executed command (getcwd, stat, uname, etc.). Since Libcox uses dynamic typing for the values it stores. Values stored in libcox_value objects can be integers, floating point values, strings, arrays and so forth.
Each libcox_value may cache multiple representations (string, integer, etc.) of the same value. There are a dozens of interfaces that allow the host application to extract and manipulates libcox_value cleanly, these includes: libcox_value_to_string(), libcox_value_int64(), libcox_value_is_float(), libcox_value_string_format() and many more.
Refer to the C/C++ Interfaces documentation for additional information.

Libcox Call Context

typedef struct libcox_context libcox_context;

The context in which a foreign command executes is stored in a libcox_context object. A pointer to a libcox_context object is always first parameter to application-defined commands. The application-defined foreign function implementation will pass this pointer through into calls to dozens of interfaces, these includes libcox_result_string(), libcox_result_value(), libcox_context_user_data() and many more. Refer to the C/C++ Interfaces documentation for additional information.

64-Bit Integer

#if defined(_MSC_VER) || defined(__BORLANDC__)
typedef signed __int64 libcox_int64;
typedef signed long long int libcox_int64;
#endif /* _MSC_VER */

Libcox uses 64-bit integer for integers arithmetic and data size regardless of the target platform. Because there is no cross-platform way to specify 64-bit integer types, libcox includes typedefs for 64-bit signed integers. The libcox_int64 type can store integer values between -9223372036854775808 and +9223372036854775807 inclusive.

Libcox VFS

#define LIBCOX_VFS_VERSION 2600 /* 2.6 */
struct libcox_vfs {
const char *zName; /* Name of this virtual file system [i.e: Windows, UNIX, etc.] */
int iVersion; /* Structure version number (currently 2.6) */
int szOsFile; /* Size of subclassed libcox_file */
int mxPathname; /* Maximum file pathname length */
/* Directory functions */
int (*xChdir)(const char *); /* Change directory */
int (*xChroot)(const char *); /* Change the root directory */
int (*xGetcwd)(libcox_context *); /* Get the current working directory */
int (*xMkdir)(const char *, int, int); /* Make directory */
int (*xRmdir)(const char *); /* Remove directory */
int (*xIsdir)(const char *); /* Tells whether the filename is a directory */
int (*xRename)(const char *, const char *); /* Renames a file or directory */
int (*xRealpath)(const char *, libcox_context *); /* Return canonicalized absolute pathname*/
/* Dir handle */
int (*xOpenDir)(const char *, libcox_value *, void **); /* Open directory handle */
void (*xCloseDir)(void *pHandle); /* Close directory handle */
int (*xDirRead)(void *pHandle, libcox_value *); /* Read the next entry from the directory handle */
void (*xDirRewind)(void *pHandle); /* Rewind the cursor */
/* Systems functions */
int (*xSleep)(unsigned int); /* Delay execution in microseconds */
int (*xUnlink)(const char *); /* Deletes a file */
int (*xFileExists)(const char *); /* Checks whether a file or directory exists */
int (*xChmod)(const char *, int); /* Changes file mode */
int (*xChown)(const char *, const char *); /* Changes file owner */
int (*xChgrp)(const char *, const char *); /* Changes file group */
libcox_int64 (*xFreeSpace)(const char *); /* Available space on filesystem or disk partition */
libcox_int64 (*xTotalSpace)(const char *); /* Total space on filesystem or disk partition */
libcox_int64 (*xFileSize)(const char *); /* Gets file size */
libcox_int64 (*xFileAtime)(const char *); /* Gets last access time of file */
libcox_int64 (*xFileMtime)(const char *); /* Gets file modification time */
libcox_int64 (*xFileCtime)(const char *); /* Gets inode change time of file */
int (*xStat)(const char *, libcox_value *, libcox_value *); /* Gives information about a file */
int (*xlStat)(const char *, libcox_value *, libcox_value *); /* Gives information about a file */
int (*xIsfile)(const char *); /* Tells whether the filename is a regular file */
int (*xIslink)(const char *); /* Tells whether the filename is a symbolic link */
int (*xReadable)(const char *); /* Tells whether a file exists and is readable */
int (*xWritable)(const char *); /* Tells whether the filename is writable */
int (*xExecutable)(const char *); /* Tells whether the filename is executable */
int (*xFiletype)(const char *, libcox_context *); /* Gets file type [i.e: fifo, dir, file..] */
int (*xGetenv)(const char *, libcox_context *); /* Gets the value of an environment variable */
int (*xSetenv)(const char *, const char *); /* Sets the value of an environment variable */
int (*xTouch)(const char *, libcox_int64, libcox_int64); /* Sets access and modification time of file */
int (*xMmap)(const char *, void **, libcox_int64 *); /* Read-only memory map of the whole file */
void (*xUnmap)(void *, libcox_int64); /* Unmap a memory view */
int (*xLink)(const char *, const char *, int); /* Create hard or symbolic link */
int (*xUmask)(int); /* Change the current umask */
void (*xTempDir)(libcox_context *); /* Get path of the temporary directory */
unsigned int (*xProcessId)(void); /* Get running process ID */
int (*xUid)(void); /* user ID of the process */
int (*xGid)(void); /* group ID of the process */
void (*xUsername)(libcox_context *); /* Running username */
int (*xSysError)(int,libcox_context *); /* Last system error message */

An instance of the libcox_vfs object defines the interface between the libcox core and the underlying operating system. The "vfs" in the name of the object stands for "Virtual File System".
Only a single vfs can be registered within the libcox core. Vfs registration is done using libcox_lib_config() with a configuration verb set to LIBCOX_LIB_CONFIG_VFS.
Note that Windows, Android, iOS and UNIX (Linux, FreeBSD, Solaris, Mac OS X, etc.) users does not have to worry about registering and installing a vfs since libcox come with a built-in vfs for these platforms that implements most the methods defined above. Clients running on exotic systems must register their own vfs in order to be able to use the libcox library.

Memory Allocation Routines

typedef struct SyMemMethods SyMemMethods;
struct SyMemMethods
void * (*xAlloc)(unsigned int); /* [Required:] Allocate a memory chunk */
void * (*xRealloc)(void *, unsigned int); /* [Required:] Re-allocate a memory chunk */
void (*xFree)(void*); /* [Required:] Release a memory chunk */
unsigned int (*xChunkSize)(void *); /* [Optional:] Return chunk size */
int (*xInit)(void*); /* [Optional:] Initialization callback */
void (*xRelease)(void *); /* [Optional:] Release callback */
void *pUserData; /* [Optional:] First argument to xInit() and xRelease() */

An instance of this object defines the interface between libcox and low-level memory allocation routines. This object is used in only one place in the libcox interface. A pointer to an instance of this object is the argument to libcox_lib_config() when the configuration option is LIBCOX_LIB_CONFIG_USER_MALLOC. An application can specify an alternative memory allocation subsystem for libcox to use for all of its dynamic memory needs.
Note that libcox is shipped with a built-in memory allocator which is perfectly adequate for the overwhelming majority of applications and that this object is only useful to a tiny minority of applications with specialized memory allocation requirements.

Mutex Methods

typedef struct SyMutexMethods SyMutexMethods;
struct SyMutexMethods
int (*xGlobalInit)(void); /* [Optional:] Global mutex initialization */
void (*xGlobalRelease)(void); /* [Optional:] Global Release callback () */
SyMutex * (*xNew)(int); /* [Required:] Request a new mutex */
void (*xRelease)(SyMutex *); /* [Optional:] Release a mutex */
void (*xEnter)(SyMutex *); /* [Required:] Enter mutex */
int (*xTryEnter)(SyMutex *); /* [Optional:] Try to enter a mutex */
void (*xLeave)(SyMutex *); /* [Required:] Leave a locked mutex */

An instance of this structure defines the low-level routines used to allocate and use mutexes. Usually, the default mutex implementations provided by libcox are sufficient, however the user has the option of substituting a custom implementation for specialized deployments or systems for which libcox does not provide a suitable implementation. In this case, the user creates and populates an instance of this structure to pass to libcox_lib_config() along with the LIBCOX_LIB_CONFIG_USER_MUTEX option.