dlite-misc

dlite-misc#

Main header file for dlite.

Wrappers around error functions

The DLITE_NOERR() and DLITE_NOERR_END macros are intended to mark a code block in which the specified errors will not be printed. Use them as follows:

DLITE_NOERR(DLITE_ERRBIT(DLiteIOError) | DLITE_ERRBIT(DLiteRuntimeError));
  // code block where IO and runtime errors are ignored
  ...
DLITE_NOERR_END;

DLITE_ERRBIT(code)#

DLITE_NOERR(mask)#

DLITE_NOERR_END#

dlite_deprecation_warning(version_removed, descr)#

typedef int64_t DLiteErrMask#

DLiteErrMask *_dlite_err_mask_get(void)#

void _dlite_err_mask_set(DLiteErrMask mask)#

void dlite_err_ignored_set(DLiteErrCode code, int value)#: Set whether to ignore printing given error code.

int dlite_err_ignored_get(DLiteErrCode code)#: Return whether printing is ignored for given error code.

void dlite_fatal(int eval, const char *msg, ...)#

void dlite_fatalx(int eval, const char *msg, ...)#

int dlite_err(int eval, const char *msg, ...)#

int dlite_errx(int eval, const char *msg, ...)#

int dlite_warn(const char *msg, ...)#

int dlite_warnx(const char *msg, ...)#

void dlite_vfatal(int eval, const char *msg, va_list ap)#

void dlite_vfatalx(int eval, const char *msg, va_list ap)#

int dlite_verr(int eval, const char *msg, va_list ap)#

int dlite_verrx(int eval, const char *msg, va_list ap)#

int dlite_vwarn(const char *msg, va_list ap)#

int dlite_vwarnx(const char *msg, va_list ap)#

int dlite_errval(void)#

const char *dlite_errmsg(void)#

void dlite_errclr(void)#

FILE *dlite_err_get_stream(void)#

void dlite_err_set_stream(FILE *stream)#

void dlite_err_set_file(const char *filename)#

int dlite_err_set_warn_mode(int mode)#

int dlite_err_get_warn_mode(void)#

int dlite_err_set_debug_mode(int mode)#

int dlite_err_get_debug_mode(void)#

int dlite_err_set_override_mode(int mode)#

int dlite_err_get_override_mode(void)#

int _dlite_deprecation_warning(const char *version_removed, const char *filepos, const char *func, const char *descr)#

Parsing options

enum DLiteOptFlag#

Values:

enumerator dliteOptDefault#: Default option flags

enumerator dliteOptStrict#: Stict mode. Its an error if option is unknown

typedef struct _DLiteOpt DLiteOpt#: Struct used by dlite_getopt()

int dlite_option_parse(char *options, DLiteOpt *opts, DLiteOptFlag flags)#

Parses the options string options and assign corresponding values of the array opts. The options string should be a valid url query string of the form:

key1=value1;key2=value2...

where the values should be encoded with uri_encode() and terminated by NUL or any of the characters in “;&#”. A hash (#) terminates the options.

At return, options is modified. All values in the options string will be URI decoded and NUL-terminated.

opts should be a NULL-terminated DLiteOpt array initialised with default values. At return, the values of the provided options are updated.

flags should be zero or dliteOptStrict.

Returns non-zero on error.

Example

If the opts array only contains a few elements, accessing it by index is probably the most convinient. However, if it contains many elements, switch might be a better option using the following pattern:

int i;
DLiteOpt opts[] = {
  {'1', "key1", "default1", "description of key1..."},
  {'b', "key2", "default2", "description of key2..."},
  {NULL, NULL}
};
dlite_getopt(options, opts);
for (i=0; opts[i].key; i++) {
  switch (opts[i].c) {
  case '1':
    // process option key1
    break;
  case 'b':
    // process option key2
    break;
  }
}

Managing global state

typedef struct _Session DLiteGlobals#: Globals handle.

void dlite_init(void)#

void dlite_finalize(void)#

DLiteGlobals *dlite_globals_get(void)#: Returns reference to globals handle.

void dlite_globals_set(DLiteGlobals *globals_handler)#: Set globals handle.

int dlite_globals_add_state(const char *name, void *ptr, void (*free_fun)(void *ptr))#

Add global state with given name.

ptr is a pointer to the state and free_fun is a function that frees it. Returns non-zero on error.

int dlite_globals_remove_state(const char *name)#: Remove global state with the given name. Returns non-zero on error.

void *dlite_globals_get_state(const char *name)#: Returns global state with given name or NULL on error.

int dlite_globals_in_atexit(void)#: Returns non-zero if we are in an atexit handler.

void dlite_globals_set_atexit(void)#: Mark that we are in an atexit handler.

General dlite utility functions

const char *dlite_get_version(void)#: Returns static pointer to a string with the current version of DLite.

FUPlatform dlite_get_platform(void)#: Returns current platform based on the DLITE_PLATFORM environment variable. Used when initiating paths.

int dlite_get_uuid(char *buff, const char *id)#

Writes an UUID to buff based on id.

Whether and what kind of UUID that is generated depends on id:

If id is NULL or empty, a new random version 4 UUID is generated.
If id is not a valid UUID string, a new version 5 sha1-based UUID is generated from id using the DNS namespace.
Otherwise is id already a valid UUID and it is simply copied to buff.

Length of buff must at least (DLITE_UUID_LENGTH + 1) bytes (36 bytes for UUID + NUL termination).

Returns the UUID version if a new UUID is generated or zero if id is already a valid UUID. On error, -1 is returned.

int dlite_get_uuidn(char *buff, const char *id, size_t len)#: Like dlite_get_uuid(), but takes the the length of id as an additional parameter.

char *dlite_join_meta_uri(const char *name, const char *version, const char *namespace)#

Returns an unique uri for metadata defined by name, version and namespace as a newly malloc()’ed string or NULL on error.

The returned uri is constructed as follows:

namespace/version/name

int dlite_split_meta_uri(const char *uri, char **name, char **version, char **namespace)#

Splits metadata uri into its components. If name, version and/or namespace are not NULL, the memory they points to will be set to a pointer to a newly malloc()’ed string with the corresponding value.

Returns non-zero on error.

Path handling

char *dlite_join_url(const char *driver, const char *location, const char *options, const char *fragment)#

Returns a newly allocated url constructed from the arguments of the form

driver://location?options#fragment

The driver, options and fragment arguments may be NULL. Returns NULL on error.

int dlite_split_url(char *url, char **driver, char **location, char **options, char **fragment)#

Splits an url of the form

driver://location?options#fragment

into four parts: driver, location, options and fragment. For the arguments that are not NULL, the pointers they points to will be assigned to point to the corresponding section within url.

This function modifies url. Make a copy if you don’t want that.

Returns non-zero on error.

Note

: URLs are assumed to have the following syntax (ref. wikipedia):

URL = scheme:[//authority]path[?query][#fragment]

where the authority component divides into three subcomponents:

authority = [userinfo@]host[:port]

This function maps scheme to driver, [authority]path to location query to options and fragment to fragment.

int dlite_split_url_winpath(char *url, char **driver, char **location, char **options, char **fragment, int winpath)#

Like dlite_split_url(), but with one additional argument.

If winpath is non-zero and url

starts with “C:" or “C:/”, then

the initial “C” is not treated as a driver, but rather as a part of the location.

int dlite_use_build_root(void)#: Returns non-zero if paths should refer to build root instead of installation root.

void dlite_set_use_build_root(int v)#: Sets whether paths should refer to build root. Default is the installation root, unless the environment variable DLITE_USE_BUILD_ROOT is set and is not false.

const char *dlite_root_get(void)#: Returns pointer to installation root. It may be altered with environment variable DLITE_ROOT.

const char *dlite_pkg_root_get(void)#

Returns pointer to the DLite package installation root.

It may be altered with environment variable DLITE_PKG_ROOT. With Python, it defaults to the DLite Python root directory, otherwise it defaults to DLITE_ROOT.

int dlite_add_dll_path(void)#

On Windows, this function adds default directories to the DLL search path. Based on whether the DLITE_USE_BUILDROOT environment variable is defined, the library directories under either the build directory or the installation root (environment variable DLITE_ROOT) are added to the DLL search path using AddDllDirectory().

On Linux this function does nothing.

Returns non-zero on error.

Functions controlling whether to hide warnings

Warning parameters:

warnings_hide: whether to hide warnings (see below).
warnings_pattern: glob pattern matching the warning message.

If warnings_pattern is NULL, warnings are hidden if warnings_hide is non-zero.

If warnings_pattern is not NULL, then warnings are hidden if:

warnings_pattern match the warning message and warnings_hide is non-zero.
warnings_pattern don’t match the warning message and warnings_hide is zero.

int dlite_get_warnings_hide(const char **pattern)#

Return parameters controlling whether warnings should be hidden.

If *pattern is not NULL, it is assigned to a static pointer to warnings_pattern (owned by DLite).

Returns warnings_hide.

void dlite_set_warnings_hide(int hide, char *pattern)#: Set parameters controlling whether warnings should be hidden.

Defines

DLITE_UUID_LENGTH#: length of an uuid (excl. NUL-termination)

struct _DLiteOpt#

#include <dlite-misc.h>

Struct used by dlite_getopt()

Public Members

int c#: Integer identifier for this option

const char *key#: Option key

const char *value#: Option value, initialised with default value

const char *descr#: Description of this option

dlite-misc

Contents

dlite-misc#