libwebsockets
Lightweight C library for HTML5 websockets
lws-misc.h
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  */
24 
25 #if defined(LWS_WITH_SPAWN)
26 
27 #if defined(WIN32) || defined(_WIN32)
28 #else
29 #include <sys/wait.h>
30 #include <sys/times.h>
31 #endif
32 #endif
33 
39 
41 struct lws_buflist;
42 
53 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
54 lws_buflist_append_segment(struct lws_buflist **head, const uint8_t *buf,
55  size_t len);
66 LWS_VISIBLE LWS_EXTERN size_t
67 lws_buflist_next_segment_len(struct lws_buflist **head, uint8_t **buf);
68 
84 LWS_VISIBLE LWS_EXTERN size_t
85 lws_buflist_use_segment(struct lws_buflist **head, size_t len);
86 
94 LWS_VISIBLE LWS_EXTERN size_t
95 lws_buflist_total_len(struct lws_buflist **head);
96 
108 LWS_VISIBLE LWS_EXTERN int
109 lws_buflist_linear_copy(struct lws_buflist **head, size_t ofs, uint8_t *buf,
110  size_t len);
111 
120 LWS_VISIBLE LWS_EXTERN void
121 lws_buflist_destroy_all_segments(struct lws_buflist **head);
122 
133 LWS_VISIBLE LWS_EXTERN void
134 lws_buflist_describe(struct lws_buflist **head, void *id, const char *reason);
135 
145 #define lws_ptr_diff(head, tail) \
146  ((int)((char *)(head) - (char *)(tail)))
147 
159 LWS_VISIBLE LWS_EXTERN int
160 lws_snprintf(char *str, size_t size, const char *format, ...) LWS_FORMAT(3);
161 
172 LWS_VISIBLE LWS_EXTERN char *
173 lws_strncpy(char *dest, const char *src, size_t size);
174 
175 /*
176  * Variation where we want to use the smaller of two lengths, useful when the
177  * source string is not NUL terminated
178  */
179 #define lws_strnncpy(dest, src, size1, destsize) \
180  lws_strncpy(dest, src, (size_t)(size1 + 1) < (size_t)(destsize) ? \
181  (size_t)(size1 + 1) : (size_t)(destsize))
182 
196 LWS_VISIBLE LWS_EXTERN const char *
197 lws_nstrstr(const char *buf, size_t len, const char *name, size_t nl);
198 
221 LWS_VISIBLE LWS_EXTERN const char *
222 lws_json_simple_find(const char *buf, size_t len, const char *name, size_t *alen);
223 
241 LWS_VISIBLE LWS_EXTERN int
242 lws_json_simple_strcmp(const char *buf, size_t len, const char *name, const char *comp);
243 
244 
261 LWS_VISIBLE LWS_EXTERN int
262 lws_hex_to_byte_array(const char *h, uint8_t *dest, int max);
263 
264 
281 LWS_VISIBLE LWS_EXTERN int
282 lws_hex_random(struct lws_context *context, char *dest, size_t len);
283 
284 /*
285  * lws_timingsafe_bcmp(): constant time memcmp
286  *
287  * \param a: first buffer
288  * \param b: second buffer
289  * \param len: count of bytes to compare
290  *
291  * Return 0 if the two buffers are the same, else nonzero.
292  *
293  * Always compares all of the buffer before returning, so it can't be used as
294  * a timing oracle.
295  */
296 
297 LWS_VISIBLE LWS_EXTERN int
298 lws_timingsafe_bcmp(const void *a, const void *b, uint32_t len);
299 
310 LWS_VISIBLE LWS_EXTERN size_t
311 lws_get_random(struct lws_context *context, void *buf, size_t len);
319 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
320 lws_daemonize(const char *_lock_path);
326 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
328 
335 LWS_VISIBLE LWS_EXTERN void *
336 lws_wsi_user(struct lws *wsi);
337 
344 LWS_VISIBLE LWS_EXTERN int
345 lws_wsi_tsi(struct lws *wsi);
346 
357 LWS_VISIBLE LWS_EXTERN void
358 lws_set_wsi_user(struct lws *wsi, void *user);
359 
382 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
383 lws_parse_uri(char *p, const char **prot, const char **ads, int *port,
384  const char **path);
402 LWS_VISIBLE LWS_EXTERN const char *
403 lws_cmdline_option(int argc, const char **argv, const char *val);
404 
417 LWS_VISIBLE LWS_EXTERN void
418 lws_cmdline_option_handle_builtin(int argc, const char **argv,
419  struct lws_context_creation_info *info);
420 
424 LWS_VISIBLE LWS_EXTERN unsigned long
426 
430 LWS_VISIBLE LWS_EXTERN lws_usec_t
432 
442 LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT
443 lws_get_context(const struct lws *wsi);
444 
454 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
455 lws_get_vhost_listen_port(struct lws_vhost *vhost);
456 
466 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
467 lws_get_count_threads(struct lws_context *context);
468 
476 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
477 lws_get_parent(const struct lws *wsi);
478 
485 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
486 lws_get_child(const struct lws *wsi);
487 
500 LWS_VISIBLE LWS_EXTERN void
501 lws_get_effective_uid_gid(struct lws_context *context, int *uid, int *gid);
502 
510 LWS_VISIBLE LWS_EXTERN const struct lws_udp * LWS_WARN_UNUSED_RESULT
511 lws_get_udp(const struct lws *wsi);
512 
513 LWS_VISIBLE LWS_EXTERN void *
514 lws_get_opaque_parent_data(const struct lws *wsi);
515 
516 LWS_VISIBLE LWS_EXTERN void
517 lws_set_opaque_parent_data(struct lws *wsi, void *data);
518 
519 LWS_VISIBLE LWS_EXTERN void *
520 lws_get_opaque_user_data(const struct lws *wsi);
521 
522 LWS_VISIBLE LWS_EXTERN void
523 lws_set_opaque_user_data(struct lws *wsi, void *data);
524 
525 LWS_VISIBLE LWS_EXTERN int
526 lws_get_child_pending_on_writable(const struct lws *wsi);
527 
528 LWS_VISIBLE LWS_EXTERN void
529 lws_clear_child_pending_on_writable(struct lws *wsi);
530 
531 LWS_VISIBLE LWS_EXTERN int
532 lws_get_close_length(struct lws *wsi);
533 
534 LWS_VISIBLE LWS_EXTERN unsigned char *
535 lws_get_close_payload(struct lws *wsi);
536 
547 LWS_VISIBLE LWS_EXTERN
548 struct lws *lws_get_network_wsi(struct lws *wsi);
549 
557 LWS_VISIBLE LWS_EXTERN void
558 lws_set_allocator(void *(*realloc)(void *ptr, size_t size, const char *reason));
559 
560 enum {
561  /*
562  * Flags for enable and disable rxflow with reason bitmap and with
563  * backwards-compatible single bool
564  */
565  LWS_RXFLOW_REASON_USER_BOOL = (1 << 0),
566  LWS_RXFLOW_REASON_HTTP_RXBUFFER = (1 << 6),
567  LWS_RXFLOW_REASON_H2_PPS_PENDING = (1 << 7),
568 
569  LWS_RXFLOW_REASON_APPLIES = (1 << 14),
570  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT = (1 << 13),
571  LWS_RXFLOW_REASON_APPLIES_ENABLE = LWS_RXFLOW_REASON_APPLIES |
572  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT,
573  LWS_RXFLOW_REASON_APPLIES_DISABLE = LWS_RXFLOW_REASON_APPLIES,
574  LWS_RXFLOW_REASON_FLAG_PROCESS_NOW = (1 << 12),
575 
576 };
577 
597 LWS_VISIBLE LWS_EXTERN int
598 lws_rx_flow_control(struct lws *wsi, int enable);
599 
609 LWS_VISIBLE LWS_EXTERN void
610 lws_rx_flow_allow_all_protocol(const struct lws_context *context,
611  const struct lws_protocols *protocol);
612 
632 LWS_VISIBLE LWS_EXTERN size_t
634 
635 #if defined(LWS_WITH_DIR)
636 
637 typedef enum {
638  LDOT_UNKNOWN,
639  LDOT_FILE,
640  LDOT_DIR,
641  LDOT_LINK,
642  LDOT_FIFO,
643  LDOTT_SOCKET,
644  LDOT_CHAR,
645  LDOT_BLOCK
646 } lws_dir_obj_type_t;
647 
648 struct lws_dir_entry {
649  const char *name;
650  lws_dir_obj_type_t type;
651 };
652 
653 typedef int
654 lws_dir_callback_function(const char *dirpath, void *user,
655  struct lws_dir_entry *lde);
656 
669 LWS_VISIBLE LWS_EXTERN int
670 lws_dir(const char *dirpath, void *user, lws_dir_callback_function cb);
671 
683 LWS_VISIBLE LWS_EXTERN int
684 lws_dir_rm_rf_cb(const char *dirpath, void *user, struct lws_dir_entry *lde);
685 
686 /*
687  * We pass every file in the base dir through a filter, and call back on the
688  * ones that match. Directories are ignored.
689  *
690  * The original path filter string may look like, eg, "sai-*.deb" or "*.txt"
691  */
692 
693 typedef int (*lws_dir_glob_cb_t)(void *data, const char *path);
694 
695 typedef struct lws_dir_glob {
696  const char *filter;
697  lws_dir_glob_cb_t cb;
698  void *user;
699 } lws_dir_glob_t;
700 
715 LWS_VISIBLE LWS_EXTERN int
716 lws_dir_glob_cb(const char *dirpath, void *user, struct lws_dir_entry *lde);
717 
718 #endif
719 
736 
743 LWS_VISIBLE LWS_EXTERN int
744 lws_get_tsi(struct lws *wsi);
745 
752 LWS_VISIBLE LWS_EXTERN int
753 lws_is_ssl(struct lws *wsi);
759 LWS_VISIBLE LWS_EXTERN int
760 lws_is_cgi(struct lws *wsi);
761 
772 LWS_VISIBLE LWS_EXTERN int
773 lws_open(const char *__file, int __oflag, ...);
774 
775 struct lws_wifi_scan { /* generic wlan scan item */
776  struct lws_wifi_scan *next;
777  char ssid[32];
778  int32_t rssi; /* divide by .count to get db */
779  uint8_t bssid[6];
780  uint8_t count;
781  uint8_t channel;
782  uint8_t authmode;
783 };
784 
785 #if defined(LWS_WITH_TLS) && !defined(LWS_WITH_MBEDTLS)
786 
792 LWS_VISIBLE LWS_EXTERN SSL*
793 lws_get_ssl(struct lws *wsi);
794 #endif
795 
796 LWS_VISIBLE LWS_EXTERN void
797 lws_explicit_bzero(void *p, size_t len);
798 
799 typedef struct lws_humanize_unit {
800  const char *name; /* array ends with NULL name */
801  uint64_t factor;
803 
804 LWS_VISIBLE extern const lws_humanize_unit_t humanize_schema_si[7];
805 LWS_VISIBLE extern const lws_humanize_unit_t humanize_schema_si_bytes[7];
806 LWS_VISIBLE extern const lws_humanize_unit_t humanize_schema_us[8];
807 
829 LWS_VISIBLE LWS_EXTERN int
830 lws_humanize(char *buf, int len, uint64_t value,
831  const lws_humanize_unit_t *schema);
832 
833 LWS_VISIBLE LWS_EXTERN void
834 lws_ser_wu16be(uint8_t *b, uint16_t u);
835 
836 LWS_VISIBLE LWS_EXTERN void
837 lws_ser_wu32be(uint8_t *b, uint32_t u32);
838 
839 LWS_VISIBLE LWS_EXTERN void
840 lws_ser_wu64be(uint8_t *b, uint64_t u64);
841 
842 LWS_VISIBLE LWS_EXTERN uint16_t
843 lws_ser_ru16be(const uint8_t *b);
844 
845 LWS_VISIBLE LWS_EXTERN uint32_t
846 lws_ser_ru32be(const uint8_t *b);
847 
848 LWS_VISIBLE LWS_EXTERN uint64_t
849 lws_ser_ru64be(const uint8_t *b);
850 
851 LWS_VISIBLE LWS_EXTERN int
852 lws_vbi_encode(uint64_t value, void *buf);
853 
854 LWS_VISIBLE LWS_EXTERN int
855 lws_vbi_decode(const void *buf, uint64_t *value, size_t len);
856 
858 
859 #if defined(LWS_WITH_SPAWN)
860 
861 /* opaque internal struct */
862 struct lws_spawn_piped;
863 
864 #if defined(WIN32)
865 struct _lws_siginfo_t {
866  int retcode;
867 };
868 typedef struct _lws_siginfo_t siginfo_t;
869 #endif
870 
871 typedef void (*lsp_cb_t)(void *opaque, lws_usec_t *accounting, siginfo_t *si,
872  int we_killed_him);
873 
874 
892 struct lws_spawn_piped_info {
893  struct lws_dll2_owner *owner;
894  struct lws_vhost *vh;
895  struct lws *opt_parent;
896 
897  const char * const *exec_array;
898  char **env_array;
899  const char *protocol_name;
900  const char *chroot_path;
901  const char *wd;
902 
903  struct lws_spawn_piped **plsp;
904 
905  void *opaque;
906 
907  lsp_cb_t reap_cb;
908 
909  lws_usec_t timeout_us;
910  int max_log_lines;
911  int tsi;
912 
913  const struct lws_role_ops *ops; /* NULL is raw file */
914 
915  uint8_t disable_ctrlc;
916 };
917 
939 LWS_VISIBLE LWS_EXTERN struct lws_spawn_piped *
940 lws_spawn_piped(const struct lws_spawn_piped_info *lspi);
941 
942 /*
943  * lws_spawn_piped_kill_child_process() - attempt to kill child process
944  *
945  * \p lsp: child object to kill
946  *
947  * Attempts to signal the child process in \p lsp to terminate.
948  */
949 LWS_VISIBLE LWS_EXTERN int
950 lws_spawn_piped_kill_child_process(struct lws_spawn_piped *lsp);
951 
965 LWS_VISIBLE LWS_EXTERN void
966 lws_spawn_stdwsi_closed(struct lws_spawn_piped *lsp, struct lws *wsi);
967 
978 LWS_VISIBLE LWS_EXTERN int
979 lws_spawn_get_stdfd(struct lws *wsi);
980 
981 #endif
982 
983 struct lws_fsmount {
984  const char *layers_path; /* where layers live */
985  const char *overlay_path; /* where overlay instantiations live */
986 
987  char mp[256]; /* mountpoint path */
988  char ovname[64]; /* unique name for mount instance */
989  char distro[64]; /* unique name for layer source */
990 
991 #if defined(__linux__)
992  const char *layers[4]; /* distro layers, like "base", "env" */
993 #endif
994 };
995 
1029 LWS_VISIBLE LWS_EXTERN int
1030 lws_fsmount_mount(struct lws_fsmount *fsm);
1031 
1044 LWS_VISIBLE LWS_EXTERN int
1045 lws_fsmount_unmount(struct lws_fsmount *fsm);
lws_get_allocated_heap
size_t lws_get_allocated_heap(void)
lws_cmdline_option
LWS_VISIBLE LWS_EXTERN const char * lws_cmdline_option(int argc, const char **argv, const char *val)
lws_humanize_unit
Definition: lws-misc.h:799
lws_set_wsi_user
LWS_VISIBLE LWS_EXTERN void lws_set_wsi_user(struct lws *wsi, void *user)
lws_get_child
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT lws_get_child(const struct lws *wsi)
lws_get_count_threads
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_get_count_threads(struct lws_context *context)
lws_buflist_total_len
LWS_VISIBLE LWS_EXTERN size_t lws_buflist_total_len(struct lws_buflist **head)
lws_json_simple_find
LWS_VISIBLE LWS_EXTERN const char * lws_json_simple_find(const char *buf, size_t len, const char *name, size_t *alen)
lws_daemonize
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_daemonize(const char *_lock_path)
lws_wsi_tsi
LWS_VISIBLE LWS_EXTERN int lws_wsi_tsi(struct lws *wsi)
lws_buflist_describe
LWS_VISIBLE LWS_EXTERN void lws_buflist_describe(struct lws_buflist **head, void *id, const char *reason)
lws_hex_random
LWS_VISIBLE LWS_EXTERN int lws_hex_random(struct lws_context *context, char *dest, size_t len)
lws_parse_uri
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_nstrstr
LWS_VISIBLE LWS_EXTERN const char * lws_nstrstr(const char *buf, size_t len, const char *name, size_t nl)
lws_get_library_version
LWS_VISIBLE LWS_EXTERN const char *LWS_WARN_UNUSED_RESULT lws_get_library_version(void)
lws_rx_flow_allow_all_protocol
LWS_VISIBLE LWS_EXTERN void lws_rx_flow_allow_all_protocol(const struct lws_context *context, const struct lws_protocols *protocol)
lws_dll2_owner
Definition: lws-dll2.h:203
lws_context_creation_info
Definition: lws-context-vhost.h:257
lws_rx_flow_control
LWS_VISIBLE LWS_EXTERN int lws_rx_flow_control(struct lws *wsi, int enable)
lws_get_tsi
LWS_VISIBLE LWS_EXTERN int lws_get_tsi(struct lws *wsi)
lws_buflist_linear_copy
LWS_VISIBLE LWS_EXTERN int lws_buflist_linear_copy(struct lws_buflist **head, size_t ofs, uint8_t *buf, size_t len)
lws_is_cgi
LWS_VISIBLE LWS_EXTERN int lws_is_cgi(struct lws *wsi)
lws_open
LWS_VISIBLE LWS_EXTERN int lws_open(const char *__file, int __oflag,...)
lws_buflist_use_segment
LWS_VISIBLE LWS_EXTERN size_t lws_buflist_use_segment(struct lws_buflist **head, size_t len)
lws_wsi_user
LWS_VISIBLE LWS_EXTERN void * lws_wsi_user(struct lws *wsi)
lws_get_parent
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT lws_get_parent(const struct lws *wsi)
lws_json_simple_strcmp
LWS_VISIBLE LWS_EXTERN int lws_json_simple_strcmp(const char *buf, size_t len, const char *name, const char *comp)
lws_snprintf
LWS_VISIBLE LWS_EXTERN int lws_snprintf(char *str, size_t size, const char *format,...) LWS_FORMAT(3)
lws_buflist_append_segment
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_remaining_packet_payload
LWS_VISIBLE LWS_EXTERN size_t lws_remaining_packet_payload(struct lws *wsi)
lws_hex_to_byte_array
LWS_VISIBLE LWS_EXTERN int lws_hex_to_byte_array(const char *h, uint8_t *dest, int max)
lws_buflist_next_segment_len
LWS_VISIBLE LWS_EXTERN size_t lws_buflist_next_segment_len(struct lws_buflist **head, uint8_t **buf)
lws_get_effective_uid_gid
LWS_VISIBLE LWS_EXTERN void lws_get_effective_uid_gid(struct lws_context *context, int *uid, int *gid)
lws_now_usecs
LWS_VISIBLE LWS_EXTERN lws_usec_t lws_now_usecs(void)
lws_strncpy
LWS_VISIBLE LWS_EXTERN char * lws_strncpy(char *dest, const char *src, size_t size)
lws_protocols
Definition: lws-protocols-plugins.h:44
lws_cmdline_option_handle_builtin
LWS_VISIBLE LWS_EXTERN void lws_cmdline_option_handle_builtin(int argc, const char **argv, struct lws_context_creation_info *info)
lws_get_network_wsi
LWS_VISIBLE LWS_EXTERN struct lws * lws_get_network_wsi(struct lws *wsi)
lws_get_vhost_listen_port
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_get_vhost_listen_port(struct lws_vhost *vhost)
lws_get_random
LWS_VISIBLE LWS_EXTERN size_t lws_get_random(struct lws_context *context, void *buf, size_t len)
lws_fsmount
Definition: lws-misc.h:983
lws_is_ssl
LWS_VISIBLE LWS_EXTERN int lws_is_ssl(struct lws *wsi)
lws_humanize
LWS_VISIBLE LWS_EXTERN int lws_humanize(char *buf, int len, uint64_t value, const lws_humanize_unit_t *schema)
lws_buflist_destroy_all_segments
LWS_VISIBLE LWS_EXTERN void lws_buflist_destroy_all_segments(struct lws_buflist **head)
lws_wifi_scan
Definition: lws-misc.h:775
lws_get_context
LWS_VISIBLE LWS_EXTERN struct lws_context *LWS_WARN_UNUSED_RESULT lws_get_context(const struct lws *wsi)
lws_get_udp
LWS_VISIBLE LWS_EXTERN const struct lws_udp *LWS_WARN_UNUSED_RESULT lws_get_udp(const struct lws *wsi)
lws_now_secs
LWS_VISIBLE LWS_EXTERN unsigned long lws_now_secs(void)
lws_set_allocator
LWS_VISIBLE LWS_EXTERN void lws_set_allocator(void *(*realloc)(void *ptr, size_t size, const char *reason))