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_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;


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 {


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


Sys.calloc(nmemb, size)

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


Return total available RAM in bytes.


Return free available RAM in bytes.


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


Return number of seconds since last reboot.


Sleep given number of microseconds. Return value: none.


Feed the watchdog timer. Return value: none.

JAVASCRIPT API Reference api_log.js


Log.print(level, msg)

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


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


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

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


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


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