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_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_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_buflist      **head_upstream;   /* the upstream buflist */
        struct lws_buflist      **private_heads;   /* the private reassembly heads */
        int                     private_source_idx;   /* which index to use in private_heads */
        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_heads: the private buflists
 * \param count_private_heads: the number of private buflists
 */
LWS_VISIBLE LWS_EXTERN void
lws_wsmsg_destroy(struct lws_buflist *private_heads[], size_t count_private_heads);
 
 
 
/*
 * 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);
 
/*
 * Variation where we want to use the smaller of two lengths, useful when the
 * source string is not NUL terminated
 */
#define lws_strnncpy(dest, src, size1, destsize) \
        lws_strncpy(dest, src, (size_t)(size1 + 1) < (size_t)(destsize) ? \
                                (size_t)(size1 + 1) : (size_t)(destsize))

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

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 const struct lws_udp * LWS_WARN_UNUSED_RESULT
lws_get_udp(const struct lws *wsi);
 
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_VISIBLE LWS_EXTERN void
lws_clear_child_pending_on_writable(struct lws *wsi);
 
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
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));
 
enum {
        /*
         * Flags for enable and disable rxflow with reason bitmap and with
         * backwards-compatible single bool
         */
        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_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);
 

 
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

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;
};
 
#if defined(LWS_WITH_TLS) && !defined(LWS_WITH_MBEDTLS) && !defined(LWS_WITH_BEARSSL)
LWS_VISIBLE LWS_EXTERN SSL*
lws_get_ssl(struct lws *wsi);
#endif
 
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 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 int
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);