Fork me on GitHub

Miscellaneous utility API

C API Reference cs_dbg.h

#include "cs_dbg.h"


enum cs_log_level {
  LL_NONE = -1,
  LL_ERROR = 0,
  LL_WARN = 1,
  LL_INFO = 2,
  LL_DEBUG = 3,
  LL_VERBOSE_DEBUG = 4,

  _LL_MIN = -2,
  _LL_MAX = 5,
};

void cs_log_set_level(enum cs_log_level level);

Set log level.

void cs_log_set_filter(char *source_file_name);

Set log filter. NULL (a default) logs everything.

int cs_log_print_prefix(enum cs_log_level level, const char *func,
                        const char *filename);

extern enum cs_log_level cs_log_threshold;

#if CS_ENABLE_STDIO

void cs_log_set_file(FILE *file);

void cs_log_set_file(FILE *file);

void cs_log_printf(

C API Reference cs_file.h

#include "cs_file.h"

Read whole file path in memory. It is responsibility of the caller to free() allocated memory. File content is guaranteed to be '\0'-terminated. File size is returned in size variable, which does not count terminating \0. Return: allocated memory, or NULL on error.


char *cs_read_file(const char *path, size_t *size);

Read whole file path in memory. It is responsibility of the caller to free() allocated memory. File content is guaranteed to be '\0'-terminated. File size is returned in size variable, which does not count terminating \0. Return: allocated memory, or NULL on error.

char *cs_mmap_file(const char *path, size_t *size);

C API Reference mbuf.h

#include "mbuf.h"

=== Memory Buffers

Mbufs are mutable/growing memory buffers, like C++ strings. Mbuf can append data to the end of a buffer or insert data into arbitrary position in the middle of a buffer. The buffer grows automatically when needed.


struct mbuf {
  char *buf;   /* Buffer pointer */
  size_t len;  /* Data length. Data is located between offset 0 and len. */
  size_t size; /* Buffer size allocated by realloc(1). Must be >= len */
};

Memory buffer descriptor

void mbuf_init(struct mbuf *, size_t initial_capacity);

Initialises an Mbuf. initial_capacity specifies the initial capacity of the mbuf.

void mbuf_free(struct mbuf *);

Frees the space allocated for the mbuffer and resets the mbuf structure.

size_t mbuf_append(struct mbuf *, const void *data, size_t data_size);

Appends data to the Mbuf.

Returns the number of bytes appended or 0 if out of memory.

size_t mbuf_insert(struct mbuf *, size_t, const void *, size_t);

Inserts data at a specified offset in the Mbuf.

Existing data will be shifted forwards and the buffer will be grown if necessary. Returns the number of bytes inserted.

void mbuf_remove(struct mbuf *, size_t data_size);

Removes data_size bytes from the beginning of the buffer.

void mbuf_resize(struct mbuf *, size_t new_size);

Resizes an Mbuf.

If new_size is smaller than buffer's len, the resize is not performed.

void mbuf_trim(struct mbuf *);

Shrinks an Mbuf by resizing its size to len.

C API Reference mg_str.h

#include "mg_str.h"


struct mg_str {
  const char *p; /* Memory chunk pointer */
  size_t len;    /* Memory chunk length */
};

Describes chunk of memory

struct mg_str mg_mk_str(const char *s);

Helper functions for creating mg_str struct from plain C string. NULL is allowed and becomes {NULL, 0}.

struct mg_str mg_mk_str_n(const char *s, size_t len);

int mg_vcmp(const struct mg_str *str2, const char *str1);

Cross-platform version of strcmp() where where first string is specified by struct mg_str.

int mg_vcasecmp(const struct mg_str *str2, const char *str1);

Cross-platform version of strncasecmp() where first string is specified by struct mg_str.

struct mg_str mg_strdup(const struct mg_str s);

Creates a copy of s (heap-allocated).

struct mg_str mg_strdup_nul(const struct mg_str s);

Creates a copy of s (heap-allocated). Resulting string is NUL-terminated (but NUL is not included in len).

const char *mg_strchr(const struct mg_str s, int c);

Locates character in a string.

int mg_strcmp(const struct mg_str str1, const struct mg_str str2);

int mg_strncmp(const struct mg_str str1, const struct mg_str str2, size_t n);

const char *mg_strstr(const struct mg_str haystack, const struct mg_str needle);

C API Reference str_util.h

#include "str_util.h"


size_t c_strnlen(const char *s, size_t maxlen);

int c_snprintf(char *buf, size_t buf_size, const char *format, ...);

int c_vsnprintf(char *buf, size_t buf_size, const char *format, va_list ap);

const char *c_strnstr(const char *s, const char *find, size_t slen);

Find the first occurrence of find in s, where the search is limited to the first slen characters of s.

void cs_to_hex(char *to, const unsigned char *p, size_t len);

Stringify binary data. Output buffer size must be 2 * size_of_input + 1 because each byte of input takes 2 bytes in string representation plus 1 byte for the terminating \0 character.

void cs_from_hex(char *to, const char *p, size_t len);

Convert stringified binary data back to binary. Does the reverse of cs_to_hex().

char *strdup(const char *src);

int64_t cs_to64(const char *s);

Simple string -> int64 conversion routine.

int mg_ncasecmp(const char *s1, const char *s2, size_t len);

Cross-platform version of strncasecmp().

int mg_casecmp(const char *s1, const char *s2);

Cross-platform version of strcasecmp().

int mg_asprintf(char **buf, size_t size, const char *fmt, ...);

Prints message to the buffer. If the buffer is large enough to hold the message, it returns buffer. If buffer is to small, it allocates a large enough buffer on heap and returns allocated buffer. This is a supposed use case:

char buf[5], *p = buf; mg_avprintf(&p, sizeof(buf), "%s", "hi there"); use_p_somehow(p); if (p != buf) { free(p); }

The purpose of this is to avoid malloc-ing if generated strings are small.

int mg_avprintf(char **buf, size_t size, const char *fmt, va_list ap);

Same as mg_asprintf, but takes varargs list.

const char *mg_next_comma_list_entry(const char *list, struct mg_str *val,
                                     struct mg_str *eq_val);

A helper function for traversing a comma separated list of values. It returns a list pointer shifted to the next value or NULL if the end of the list found. The value is stored in a val vector. If the value has a form "x=y", then eq_val vector is initialised to point to the "y" part, and val vector length is adjusted to point only to "x". If the list is just a comma separated list of entries, like "aa,bb,cc" then eq_val will contain zero-length string.

The purpose of this function is to parse comma separated string without any copying/memory allocation.

struct mg_str mg_next_comma_list_entry_n(struct mg_str list, struct mg_str *val,
                                         struct mg_str *eq_val);

int mg_match_prefix(const char *pattern, int pattern_len, const char *str);

Matches 0-terminated string (mg_match_prefix) or string with given length mg_match_prefix_n against a glob pattern.

Match is case-insensitive. Returns number of bytes matched, or -1 if no match.

int mg_match_prefix_n(const struct mg_str pattern, const struct mg_str str);

C API Reference mgos_hooks.h

#include "mgos_hooks.h"

Hooks API


enum mgos_hook_type {
  MGOS_HOOK_INIT_DONE,
  MGOS_HOOK_DEBUG_WRITE,

  MGOS_HOOK_TYPES_CNT
};

struct mgos_hook_arg {
  union {
    struct mgos_debug_hook_arg debug;
  };

typedef void(mgos_hook_fn_t)(enum mgos_hook_type type,
                             const struct mgos_hook_arg *arg, void *userdata);

Hook function, arg is a hook-specific arguments, userdata is an arbitrary pointer given at the hook registration time.

bool mgos_hook_register(enum mgos_hook_type type, mgos_hook_fn_t *cb,
                        void *userdata);

void mgos_hook_trigger(enum mgos_hook_type type,
                       const struct mgos_hook_arg *arg);

JAVASCRIPT API Reference api_sys.js

load("api_sys.js");


Sys.calloc(nmemb, size)

Allocate a memory region. Note: currently memory allocated this way must be explicitly released with free().

Sys.total_ram()

Return total available RAM in bytes.

Sys.free_ram()

Return free available RAM in bytes.

Sys.reboot(us)

Reboot the system after us microseconds. Return value: none.

Sys.uptime()

Return number of seconds since last reboot.

Sys.usleep(microseconds)

Sleep given number of microseconds. Return value: none.

Sys.wdt_feed()

Feed the watchdog timer. Return value: none.

JAVASCRIPT API Reference api_log.js

load("api_log.js");


Log.print(level, msg)

Print message to stderr if provided level is >= Cfg.get('debug.level')

Log.error(msg)

Shortcut for Log.print(Log.ERROR, msg)

Log.warn(msg)

Shortcut for Log.print(Log.WARN, msg)

Log.info(msg)

Shortcut for Log.print(Log.INFO, msg)

Log.debug(msg)

Shortcut for Log.print(Log.DEBUG, msg)

Log.verboseDebug(msg)

Shortcut for Log.print(Log.VERBOSE_DEBUG, msg)