lws-misc.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */
 
#if defined(LWS_WITH_SPAWN)
 
#if defined(WIN32) || defined(_WIN32)
#else
#include <sys/wait.h>
#include <sys/times.h>
#endif
#endif
 
#if defined(__OpenBSD__)
#include <sys/siginfo.h>
#endif

 
struct lws_buflist;
 
/*
 * lws_fragbuf: a large buffer that does not insist on being contiguous
 *
 * A decoder that wants tens of KB in one piece fails on a heap that has the
 * space but not in one run - and on a small target, mixed in with the
 * connections and parsers that are still live, that is the normal state of
 * affairs rather than the exception.
 *
 * Where the consumer can work with the buffer in pieces, this takes the
 * failure of the monolithic allocation as an invitation to try again in
 * smaller ones.  It still asks for the whole thing first, so when the heap
 * can do it nothing is lost: the unit table is then simply a contiguous walk
 * and lws_fragbuf_at() hands back the whole remainder at once.
 *
 * unit_size is the granularity the consumer needs contiguous, eg, a row pitch
 * for image data: a unit is never split across allocations, so
 * lws_fragbuf_unit() always hands back unit_size contiguous bytes.
 *
 * Every unit starts zeroed, whether it came in one piece or many.
 */
 
typedef struct lws_fragbuf lws_fragbuf_t;

LWS_VISIBLE LWS_EXTERN lws_fragbuf_t *
lws_fragbuf_create(size_t units, size_t unit_size);

LWS_VISIBLE LWS_EXTERN lws_fragbuf_t *
lws_fragbuf_create_cap(size_t units, size_t unit_size, size_t cap);
 
LWS_VISIBLE LWS_EXTERN void
lws_fragbuf_destroy(lws_fragbuf_t **fb);

LWS_VISIBLE LWS_EXTERN uint8_t *
lws_fragbuf_unit(const lws_fragbuf_t *fb, size_t unit);

LWS_VISIBLE LWS_EXTERN uint8_t *
lws_fragbuf_at(const lws_fragbuf_t *fb, size_t ofs, size_t *avail);

LWS_VISIBLE LWS_EXTERN unsigned int
lws_fragbuf_pieces(const lws_fragbuf_t *fb);

 
#define LWS_BUFLIST_OOM_LIMIT (2 * 1024 * 1024)
 
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_buflist_append_segment(struct lws_buflist **head, const uint8_t *buf,
                           size_t len);

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_buflist_append_segment_take_ownership(struct lws_buflist **head, uint8_t *buf, size_t len);

LWS_VISIBLE LWS_EXTERN size_t
lws_buflist_next_segment_len(struct lws_buflist **head, uint8_t **buf);

LWS_VISIBLE LWS_EXTERN size_t
lws_buflist_use_segment(struct lws_buflist **head, size_t len);

LWS_VISIBLE LWS_EXTERN size_t
lws_buflist_total_len(struct lws_buflist **head);

LWS_VISIBLE LWS_EXTERN int
lws_buflist_linear_copy(struct lws_buflist **head, size_t ofs, uint8_t *buf,
                        size_t len);

LWS_VISIBLE LWS_EXTERN int
lws_buflist_linear_use(struct lws_buflist **head, uint8_t *buf, size_t len);

LWS_VISIBLE LWS_EXTERN int
lws_buflist_fragment_use(struct lws_buflist **head, uint8_t *buf,
                         size_t len, char *frag_first, char *frag_fin);

LWS_VISIBLE LWS_EXTERN void
lws_buflist_destroy_all_segments(struct lws_buflist **head);

LWS_VISIBLE LWS_EXTERN void
lws_buflist_describe(struct lws_buflist **head, void *id, const char *reason);

LWS_VISIBLE LWS_EXTERN void *
lws_buflist_get_frag_start_or_NULL(struct lws_buflist **head);
 
 
/* --- lws_buflist2 (doubly-linked) --- */
 
struct lws_buflist2_owner {
        struct lws_dll2_owner   owner;
        size_t                  total_len;
        size_t                  limit;
};
 
struct lws_buflist2;

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_buflist2_append_segment(struct lws_buflist2_owner *owner, const uint8_t *buf,
                            size_t len);

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_buflist2_append_segment_take_ownership(struct lws_buflist2_owner *owner, uint8_t *buf, size_t len);

LWS_VISIBLE LWS_EXTERN size_t
lws_buflist2_next_segment_len(struct lws_buflist2_owner *owner, uint8_t **buf);

LWS_VISIBLE LWS_EXTERN size_t
lws_buflist2_use_segment(struct lws_buflist2_owner *owner, size_t len);

static LWS_INLINE size_t
lws_buflist2_total_len(struct lws_buflist2_owner *owner) { return owner->total_len; }

LWS_VISIBLE LWS_EXTERN int
lws_buflist2_fragment_use(struct lws_buflist2_owner *owner, uint8_t *buf,
                          size_t len, char *frag_first, char *frag_fin);

LWS_VISIBLE LWS_EXTERN void
lws_buflist2_destroy_all_segments(struct lws_buflist2_owner *owner);

LWS_VISIBLE LWS_EXTERN void *
lws_buflist2_get_frag_start_or_NULL(struct lws_buflist2_owner *owner);
 
 

LWS_VISIBLE LWS_EXTERN uint32_t
lws_crc32(uint32_t crc, const void *buf, size_t len);
 
 
 
struct lws_wsmsg_info;
 
typedef void (*lws_wsmsg_transfer_cb)(struct lws_wsmsg_info *info);
 
typedef struct lws_wsmsg_info {
        struct lws_buflist2_owner *upstream;            /* the upstream buflist */
        struct lws_buflist2_owner *private_owners;      /* array of private reassembly buflists */
        int                     private_source_idx;     /* which index to use in private_owners */
        lws_wsmsg_transfer_cb   optional_cb;            /* optional transfer callback */
        void                    *opaque;                /* optional opaque pointer */
        const uint8_t           *buf;                   /* array to add */
        size_t                  len;                    /* length of bytes in array */
        unsigned int            ss_flags;               /* SS flags for SOM / EOM */
} lws_wsmsg_info_t;

LWS_VISIBLE LWS_EXTERN int
lws_wsmsg_append(lws_wsmsg_info_t *info);
 
/*
 * lws_wsmsg_destroy() - free all allocations in private buflists
 *
 * \param private_owners: the array of private buflists
 * \param count_private_owners: the number of private buflists
 */
LWS_VISIBLE LWS_EXTERN void
lws_wsmsg_destroy(struct lws_buflist2_owner *private_owners,
                  size_t count_private_owners);
 
 
 
/*
 * Optional helpers for closely-managed stream flow control.  These are useful
 * when there is no memory for large rx buffers and instead tx credit is being
 * used to regulate the server sending data.
 *
 * When combined with stateful consumption-on-demand, this can be very effective
 * at managing data flows through restricted circumstances.  These helpers
 * implement a golden implementation that can be bound to a stream in its priv
 * data.
 *
 * The helper is sophisticated enough to contain a buflist to manage overflows
 * on heap and preferentially drain it.  RX goes through heap to guarantee the
 * consumer can exit cleanly at any time.
 */
 
enum {
        LWSDLOFLOW_STATE_READ, /* default, we want input */
        LWSDLOFLOW_STATE_READ_COMPLETED, /* we do not need further rx, every-
                                          * thing is locally buffered or used */
        LWSDLOFLOW_STATE_READ_FAILED, /* operation has fatal error */
};
 
struct lws_ss_handle;
 
typedef struct lws_flow {
        lws_dll2_t                      list;
 
        struct lws_ss_handle            *h;
        struct lws_buflist              *bl;
 
        const uint8_t                   *data;
        size_t                          len;            /* bytes left in data */
        uint32_t                        blseglen;       /* bytes issued */
        int32_t                         window;
 
        uint8_t                         state;
} lws_flow_t;

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_flow_feed(lws_flow_t *flow);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_flow_req(lws_flow_t *flow);

#define lws_ptr_diff(head, tail) \
                        ((int)((char *)(head) - (char *)(tail)))

#define lws_ptr_diff_size_t(head, tail) \
                        ((size_t)(ssize_t)((char *)(head) - (char *)(tail)))

LWS_VISIBLE LWS_EXTERN int
lws_snprintf(char *str, size_t size, const char *format, ...) LWS_FORMAT(3);

LWS_VISIBLE LWS_EXTERN char *
lws_strncpy(char *dest, const char *src, size_t size);

static LWS_INLINE size_t
lws_strnncpy_size(size_t size1, size_t destsize)
{
        if (size1 == (size_t)-1)
                /* size1 + 1 would wrap to 0, leaving dest unterminated */
                return destsize;
 
        return size1 + 1u < destsize ? size1 + 1u : destsize;
}
 
/*
 * Variation where we want to use the smaller of two lengths, useful when the
 * source string is not NUL terminated.  \p size1 is the source length, ie, one
 * less than the destination size it implies.
 */
#define lws_strnncpy(dest, src, size1, destsize) \
        lws_strncpy(dest, src, lws_strnncpy_size((size_t)(size1), \
                                                 (size_t)(destsize)))

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_check_utf8(unsigned char *state, const unsigned char *buf, size_t len);

LWS_VISIBLE LWS_EXTERN size_t
lws_utf8_trim_partial(char *s, size_t len);

LWS_VISIBLE LWS_EXTERN const char *
lws_nstrstr(const char *buf, size_t len, const char *name, size_t nl);

LWS_VISIBLE LWS_EXTERN const char *
lws_json_simple_find(const char *buf, size_t len, const char *name, size_t *alen);

LWS_VISIBLE LWS_EXTERN int
lws_json_simple_strcmp(const char *buf, size_t len, const char *name, const char *comp);

LWS_VISIBLE LWS_EXTERN int
lws_hex_len_to_byte_array(const char *h, size_t hlen, uint8_t *dest, int max);

LWS_VISIBLE LWS_EXTERN int
lws_hex_to_byte_array(const char *h, uint8_t *dest, int max);

LWS_VISIBLE LWS_EXTERN void
lws_hex_from_byte_array(const uint8_t *src, size_t slen, char *dest, size_t len);

LWS_VISIBLE LWS_EXTERN int
lws_hex_random(struct lws_context *context, char *dest, size_t len);
 
/*
 * lws_timingsafe_bcmp(): constant time memcmp
 *
 * \param a: first buffer
 * \param b: second buffer
 * \param len: count of bytes to compare
 *
 * Return 0 if the two buffers are the same, else nonzero.
 *
 * Always compares all of the buffer before returning, so it can't be used as
 * a timing oracle.
 */
 
LWS_VISIBLE LWS_EXTERN int
lws_timingsafe_bcmp(const void *a, const void *b, uint32_t len);

LWS_VISIBLE LWS_EXTERN size_t
lws_get_random(struct lws_context *context, void *buf, size_t len);
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_daemonize(const char *_lock_path);
LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
lws_get_library_version(void);

LWS_VISIBLE LWS_EXTERN void *
lws_wsi_user(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN int
lws_ensure_user_space(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN int
lws_wsi_tsi(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN void
lws_set_wsi_user(struct lws *wsi, void *user);

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_parse_uri(char *p, const char **prot, const char **ads, int *port,
              const char **path) LWS_WARN_DEPRECATED;
 
typedef struct lws_parse_uri {
        const char      *scheme;
        const char      *host;
        const char      *path;
        uint16_t        port;
        char            unix_skt;
} lws_parse_uri_t;

LWS_VISIBLE LWS_EXTERN lws_parse_uri_t * LWS_WARN_UNUSED_RESULT
lws_parse_uri_create(const char *uri);

LWS_VISIBLE LWS_EXTERN void
lws_parse_uri_destroy(lws_parse_uri_t **pcuri);
 
struct lws_switches {
        const char *sw;
        const char *doc;
};
 
LWS_VISIBLE LWS_EXTERN void
lws_switches_print_help(const char *prog, const struct lws_switches *switches, size_t count);
 

LWS_VISIBLE LWS_EXTERN const char *
lws_cmdline_option(int argc, const char **argv, const char *val);

LWS_VISIBLE LWS_EXTERN const char *
lws_cmdline_options(int argc, const char * const *argv, const char *val, const char *last);

 
LWS_VISIBLE LWS_EXTERN const char *
lws_cmdline_options_cx(const struct lws_context *cx, const char *val, const char *last);

LWS_VISIBLE LWS_EXTERN const char *
lws_cmdline_option_cx(const struct lws_context *cx, const char *val);

LWS_VISIBLE LWS_EXTERN const char *
lws_cmdline_option_cx_argv0(const struct lws_context *cx);

LWS_VISIBLE LWS_EXTERN void
lws_cmdline_option_handle_builtin(int argc, const char **argv,
                                  struct lws_context_creation_info *info);
 
#if defined(LWS_WITH_CRASH_BACKTRACE)
LWS_VISIBLE LWS_EXTERN int
lws_crash_backtrace_install(void);
#endif

LWS_VISIBLE LWS_EXTERN lws_usec_t
lws_parse_iso8601(const char *ads);

LWS_VISIBLE LWS_EXTERN unsigned long
lws_now_secs(void);

LWS_VISIBLE LWS_EXTERN lws_usec_t
lws_now_usecs(void);

LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT
lws_get_context(const struct lws *wsi);

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_get_vhost_listen_port(struct lws_vhost *vhost);

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
lws_get_count_threads(struct lws_context *context);

LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
lws_get_parent(const struct lws *wsi);

LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
lws_get_child(const struct lws *wsi);

LWS_VISIBLE LWS_EXTERN void
lws_get_effective_uid_gid(struct lws_context *context, uid_t *uid, gid_t *gid);

LWS_VISIBLE LWS_EXTERN int
lws_plat_user_to_uid(const char *username, uid_t *puid);

LWS_VISIBLE LWS_EXTERN int
lws_plat_group_to_gid(const char *groupname, gid_t *pgid);
 
LWS_VISIBLE LWS_EXTERN void *
lws_get_opaque_parent_data(const struct lws *wsi);
 
LWS_VISIBLE LWS_EXTERN void
lws_set_opaque_parent_data(struct lws *wsi, void *data);
 
LWS_VISIBLE LWS_EXTERN void *
lws_get_opaque_user_data(const struct lws *wsi);
 
LWS_VISIBLE LWS_EXTERN void
lws_set_opaque_user_data(struct lws *wsi, void *data);

LWS_VISIBLE LWS_EXTERN int
lws_get_child_pending_on_writable(const struct lws *wsi) LWS_WARN_DEPRECATED;

LWS_VISIBLE LWS_EXTERN void
lws_clear_child_pending_on_writable(struct lws *wsi) LWS_WARN_DEPRECATED;
 
LWS_VISIBLE LWS_EXTERN int
lws_get_close_length(struct lws *wsi);
 
LWS_VISIBLE LWS_EXTERN unsigned char *
lws_get_close_payload(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN int
lws_wsi_close_cause(struct lws *wsi, char *buf, size_t len);

LWS_VISIBLE LWS_EXTERN
struct lws *lws_get_network_wsi(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN void
lws_set_allocator(void *(*realloc)(void *ptr, size_t size, const char *reason));
 
/*
 * Reclaimable heap occupants
 *
 * Something that keeps bytes on the heap it could recreate from storage
 * later (a font's dictionary, an image's payload and decoder state) can
 * register as reclaimable.  When an allocation fails, the allocator asks the
 * least recently used unpinned occupants to evict what they hold, and then
 * retries: the code that wanted the memory, however deep in the stack, sees
 * only a successful allocation.  The occupant notices it is no longer
 * resident the next time it is touched and reloads then.
 *
 * evict() is called from inside the failed allocation, so it may only free
 * things, unlink list nodes and set flags: it must not allocate, and must
 * not destroy anything another part of the stack holds a pointer to.  An
 * occupant that is in use right now (a decoder mid-row, glyphs attached to
 * text being rendered) pins itself for the duration so it is skipped.
 */
 
typedef struct lws_reclaimable {
        lws_dll2_t              list;   /* LRU: oldest at the head */

        size_t                  (*evict)(struct lws_reclaimable *r);
 
        size_t                  resident; /* bytes evict() could free now */
        uint16_t                pins;     /* nonzero: in use, not evictable */
} lws_reclaimable_t;

LWS_VISIBLE LWS_EXTERN void
lws_reclaimable_add(lws_reclaimable_t *r);

LWS_VISIBLE LWS_EXTERN void
lws_reclaimable_remove(lws_reclaimable_t *r);

LWS_VISIBLE LWS_EXTERN void
lws_reclaimable_touch(lws_reclaimable_t *r);

LWS_VISIBLE LWS_EXTERN void
lws_reclaimable_pin(lws_reclaimable_t *r);
 
LWS_VISIBLE LWS_EXTERN void
lws_reclaimable_unpin(lws_reclaimable_t *r);

LWS_VISIBLE LWS_EXTERN size_t
lws_reclaim(size_t want);

LWS_VISIBLE LWS_EXTERN void
lws_heap_limit_set(size_t bytes);
 
enum {
        /*
         * Flags for enable and disable rxflow with reason bitmap and with
         * backwards-compatible single bool.  b5..b0 are the user's, the
         * reasons above them are the library's own.
         */
        LWS_RXFLOW_REASON_USER_BOOL             = (1 << 0),
        LWS_RXFLOW_REASON_HTTP_RXBUFFER         = (1 << 6),
        LWS_RXFLOW_REASON_H2_PPS_PENDING        = (1 << 7),
        LWS_RXFLOW_REASON_MQTT_ACK_TX           = (1 << 8),
        /* b11..b9 are free for more library reasons */
 
        LWS_RXFLOW_REASON_APPLIES               = (1 << 14),
        LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT    = (1 << 13),
        LWS_RXFLOW_REASON_APPLIES_ENABLE        = LWS_RXFLOW_REASON_APPLIES |
                                                  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT,
        LWS_RXFLOW_REASON_APPLIES_DISABLE       = LWS_RXFLOW_REASON_APPLIES,
        LWS_RXFLOW_REASON_FLAG_PROCESS_NOW      = (1 << 12),
 
};

LWS_VISIBLE LWS_EXTERN int
lws_rx_flow_control(struct lws *wsi, int enable);

LWS_VISIBLE LWS_EXTERN void
lws_rx_flow_allow_all_protocol(const struct lws_context *context,
                               const struct lws_protocols *protocol);

LWS_VISIBLE LWS_EXTERN size_t
lws_remaining_packet_payload(struct lws *wsi);
 
#if defined(LWS_WITH_DIR)
 
typedef enum {
        LDOT_UNKNOWN,
        LDOT_FILE,
        LDOT_DIR,
        LDOT_LINK,
        LDOT_FIFO,
        LDOTT_SOCKET,
        LDOT_CHAR,
        LDOT_BLOCK
} lws_dir_obj_type_t;
 
struct lws_dir_entry {
        const char *name;
        lws_dir_obj_type_t type;
};
 
typedef int
lws_dir_callback_function(const char *dirpath, void *user,
                          struct lws_dir_entry *lde);
 
struct lws_dir_info {
        const char                      *dirpath;
        void                            *user;
        lws_dir_callback_function       *cb;
        unsigned char                   do_toplevel_cb:1;
};

LWS_VISIBLE LWS_EXTERN int
lws_dir(const char *dirpath, void *user, lws_dir_callback_function cb);

LWS_VISIBLE LWS_EXTERN int
lws_dir_via_info(struct lws_dir_info *info);
 

LWS_VISIBLE LWS_EXTERN int
lws_dir_rm_rf_cb(const char *dirpath, void *user, struct lws_dir_entry *lde);

LWS_VISIBLE LWS_EXTERN int
lws_dir_symlink_rotate(const char *cur, const char *target,
                       const char *cur_tag, const char *prev_tag);
 

 
typedef struct lws_dir_du {
        uint64_t                        size_in_bytes;
        uint32_t                        count_files;
} lws_dir_du_t;

LWS_VISIBLE LWS_EXTERN int
lws_dir_du_cb(const char *dirpath, void *user, struct lws_dir_entry *lde);
 
 
/*
 * We pass every file in the base dir through a filter, and call back on the
 * ones that match.  Directories are ignored.
 *
 * The original path filter string may look like, eg, "sai-*.deb" or "*.txt"
 */
 
typedef int (*lws_dir_glob_cb_t)(void *data, const char *path);
 
typedef struct lws_dir_glob {
        const char              *filter;
        lws_dir_glob_cb_t       cb;
        void                    *user;
} lws_dir_glob_t;

LWS_VISIBLE LWS_EXTERN int
lws_dir_glob_cb(const char *dirpath, void *user, struct lws_dir_entry *lde);
 
#endif

LWS_VISIBLE LWS_EXTERN size_t
lws_get_allocated_heap(void);

LWS_VISIBLE LWS_EXTERN int
lws_get_tsi(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN int
lws_is_ssl(struct lws *wsi);
LWS_VISIBLE LWS_EXTERN int
lws_is_cgi(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN int
lws_tls_jit_trust_blob_queury_skid(const void *_blob, size_t blen,
                                   const uint8_t *skid, size_t skid_len,
                                   const uint8_t **prpder, size_t *prder_len);

LWS_VISIBLE LWS_EXTERN int
lws_open(const char *__file, int __oflag, ...);
 
struct lws_wifi_scan { /* generic wlan scan item */
        struct lws_wifi_scan *next;
        char ssid[32];
        int32_t rssi; /* divide by .count to get db */
        uint8_t bssid[6];
        uint8_t count;
        uint8_t channel;
        uint8_t authmode;
};
 
LWS_VISIBLE LWS_EXTERN void
lws_explicit_bzero(void *p, size_t len);
 
typedef struct lws_humanize_unit {
        const char *name; /* array ends with NULL name */
        uint64_t factor;
} lws_humanize_unit_t;
 
LWS_VISIBLE LWS_EXTERN_FOR_DATA const lws_humanize_unit_t humanize_schema_si[7];
LWS_VISIBLE LWS_EXTERN_FOR_DATA const lws_humanize_unit_t humanize_schema_si_bytes[7];
LWS_VISIBLE LWS_EXTERN_FOR_DATA const lws_humanize_unit_t humanize_schema_us[8];
 
#if defined(_DEBUG)
LWS_VISIBLE LWS_EXTERN void
lws_assert_fourcc(uint32_t fourcc, uint32_t expected);
#else
#define lws_assert_fourcc(_a, _b) do { } while (0);
#endif

 
LWS_VISIBLE LWS_EXTERN int
lws_humanize(char *buf, size_t len, uint64_t value,
             const lws_humanize_unit_t *schema);
 
LWS_VISIBLE LWS_EXTERN int
lws_humanize_pad(char *p, size_t len, uint64_t v,
                 const lws_humanize_unit_t *schema);
 
LWS_VISIBLE LWS_EXTERN void
lws_ser_wu16be(uint8_t *b, uint16_t u);
 
LWS_VISIBLE LWS_EXTERN void
lws_ser_wu32be(uint8_t *b, uint32_t u32);
 
LWS_VISIBLE LWS_EXTERN void
lws_ser_wu64be(uint8_t *b, uint64_t u64);
 
LWS_VISIBLE LWS_EXTERN uint16_t
lws_ser_ru16be(const uint8_t *b);
 
LWS_VISIBLE LWS_EXTERN uint32_t
lws_ser_ru32be(const uint8_t *b);
 
LWS_VISIBLE LWS_EXTERN uint64_t
lws_ser_ru64be(const uint8_t *b);
 
LWS_VISIBLE LWS_EXTERN int
lws_vbi_encode(uint64_t value, void *buf);
 
LWS_VISIBLE LWS_EXTERN int
lws_vbi_decode(const void *buf, uint64_t *value, size_t len);

 
#if defined(LWS_WITH_SPAWN)
 
/* opaque internal struct */
struct lws_spawn_piped;
 
#if defined(WIN32)
struct _lws_siginfo_t {
        int retcode;
};
typedef struct _lws_siginfo_t siginfo_t;
#endif

typedef struct lws_spawn_resource_us {
        uint64_t                        us_cpu_user;  
        uint64_t                        us_cpu_sys;   
 
        uint64_t                        peak_mem_rss; 
        uint64_t                        peak_mem_virt; 
} lws_spawn_resource_us_t;
 
typedef void (*lsp_cb_t)(void *opaque, const lws_spawn_resource_us_t *res,
                         siginfo_t *si, int we_killed_him);
 

struct lws_spawn_piped_info {
        struct lws_dll2_owner           *owner;
        struct lws_vhost                *vh;
        struct lws                      *opt_parent;
 
        const char * const              *exec_array;
        const char                      **env_array;
        const char                      *protocol_name;
        const char                      *chroot_path;
        const char                      *wd;
 
        struct lws_spawn_piped          **plsp;
 
        void                            *opaque;
 
        lsp_cb_t                        reap_cb;
 
        lws_spawn_resource_us_t         *res;
 
        lws_usec_t                      timeout_us;
        int                             max_log_lines;
        int                             tsi;
 
        const struct lws_role_ops       *ops; /* NULL is raw file */
 
        uint8_t                         disable_ctrlc;
        uint8_t                         pty_mode;
 
        const char                      *cgroup_name_suffix;
        int                             *p_cgroup_ret;
};

LWS_VISIBLE LWS_EXTERN struct lws_spawn_piped *
lws_spawn_piped(const struct lws_spawn_piped_info *lspi);
 
/*
 * lws_spawn_piped_kill_child_process() - attempt to kill child process
 *
 * \p lsp: child object to kill
 *
 * Attempts to signal the child process in \p lsp to terminate.
 */
LWS_VISIBLE LWS_EXTERN int
lws_spawn_piped_kill_child_process(struct lws_spawn_piped *lsp);

LWS_VISIBLE LWS_EXTERN void
lws_spawn_piped_destroy(struct lws_spawn_piped **lsp);

LWS_VISIBLE LWS_EXTERN int
lws_spawn_get_stdwsi_open_count(struct lws_spawn_piped *lsp);

LWS_VISIBLE LWS_EXTERN int
lws_spawn_stdwsi_closed(struct lws_spawn_piped *lsp, struct lws *wsi);
 
/*
 * lws_spawn_closedown_stdwsis() - forcibly close the spawner side of stdwsi pipes
 *
 * \p lsp: the spawn object
 *
 * Closes the spawner side of all the stdwsi for an lsp that are still open.
 */
LWS_VISIBLE LWS_EXTERN void
lws_spawn_closedown_stdwsis(struct lws_spawn_piped *lsp);

LWS_VISIBLE LWS_EXTERN int
lws_spawn_get_stdfd(struct lws *wsi);

LWS_VISIBLE LWS_EXTERN lws_filefd_type
lws_spawn_get_fd_stdxxx(struct lws_spawn_piped *lsp, int std_idx);

LWS_VISIBLE LWS_EXTERN int
lws_spawn_prepare_self_cgroup(const char *user, const char *group);

LWS_VISIBLE LWS_EXTERN int
lws_spawn_get_self_cgroup(char *cgroup, size_t max);
 
#endif
 
struct lws_fsmount {
        const char      *layers_path;   /* where layers live */
        const char      *overlay_path;  /* where overlay instantiations live */
 
        char            mp[256];        /* mountpoint path */
        char            ovname[64];     /* unique name for mount instance */
        char            distro[64];     /* unique name for layer source */
 
#if defined(__linux__)
        const char      *layers[4];     /* distro layers, like "base", "env" */
#endif
};

LWS_VISIBLE LWS_EXTERN int
lws_fsmount_mount(struct lws_fsmount *fsm);

LWS_VISIBLE LWS_EXTERN int
lws_fsmount_unmount(struct lws_fsmount *fsm);
 
#define LWS_MINILEX_FAIL -1
#define LWS_MINILEX_CONTINUE 0
#define LWS_MINILEX_MATCH 1

LWS_VISIBLE LWS_EXTERN int
lws_minilex_parse(const uint8_t *lex, int16_t *ps, const uint8_t c,
                        int *match);
 
/*
 * Reports the number of significant bits (from the left) that is needed to
 * represent u.  So if u is 0x80, result is 8.
 */
 
LWS_VISIBLE LWS_EXTERN unsigned int
lws_sigbits(uintptr_t u);

LWS_VISIBLE LWS_EXTERN int
lws_wol(struct lws_context *ctx, const char *ip_or_NULL, uint8_t *mac_6_bytes);