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 
199 LWS_VISIBLE LWS_EXTERN int
200 lws_hex_to_byte_array(const char *h, uint8_t *dest, int max);
201 
202 /*
203  * lws_timingsafe_bcmp(): constant time memcmp
204  *
205  * \param a: first buffer
206  * \param b: second buffer
207  * \param len: count of bytes to compare
208  *
209  * Return 0 if the two buffers are the same, else nonzero.
210  *
211  * Always compares all of the buffer before returning, so it can't be used as
212  * a timing oracle.
213  */
214 
215 LWS_VISIBLE LWS_EXTERN int
216 lws_timingsafe_bcmp(const void *a, const void *b, uint32_t len);
217 
228 LWS_VISIBLE LWS_EXTERN size_t
229 lws_get_random(struct lws_context *context, void *buf, size_t len);
237 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
238 lws_daemonize(const char *_lock_path);
244 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT
246 
253 LWS_VISIBLE LWS_EXTERN void *
254 lws_wsi_user(struct lws *wsi);
255 
266 LWS_VISIBLE LWS_EXTERN void
267 lws_set_wsi_user(struct lws *wsi, void *user);
268 
291 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
292 lws_parse_uri(char *p, const char **prot, const char **ads, int *port,
293  const char **path);
311 LWS_VISIBLE LWS_EXTERN const char *
312 lws_cmdline_option(int argc, const char **argv, const char *val);
313 
326 LWS_VISIBLE LWS_EXTERN void
327 lws_cmdline_option_handle_builtin(int argc, const char **argv,
328  struct lws_context_creation_info *info);
329 
333 LWS_VISIBLE LWS_EXTERN unsigned long
334 lws_now_secs(void);
335 
339 LWS_VISIBLE LWS_EXTERN lws_usec_t
340 lws_now_usecs(void);
341 
351 LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT
352 lws_get_context(const struct lws *wsi);
353 
363 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
364 lws_get_vhost_listen_port(struct lws_vhost *vhost);
365 
375 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
376 lws_get_count_threads(struct lws_context *context);
377 
385 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
386 lws_get_parent(const struct lws *wsi);
387 
394 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT
395 lws_get_child(const struct lws *wsi);
396 
409 LWS_VISIBLE LWS_EXTERN void
410 lws_get_effective_uid_gid(struct lws_context *context, int *uid, int *gid);
411 
419 LWS_VISIBLE LWS_EXTERN const struct lws_udp * LWS_WARN_UNUSED_RESULT
420 lws_get_udp(const struct lws *wsi);
421 
422 LWS_VISIBLE LWS_EXTERN void *
423 lws_get_opaque_parent_data(const struct lws *wsi);
424 
425 LWS_VISIBLE LWS_EXTERN void
426 lws_set_opaque_parent_data(struct lws *wsi, void *data);
427 
428 LWS_VISIBLE LWS_EXTERN void *
429 lws_get_opaque_user_data(const struct lws *wsi);
430 
431 LWS_VISIBLE LWS_EXTERN void
432 lws_set_opaque_user_data(struct lws *wsi, void *data);
433 
434 LWS_VISIBLE LWS_EXTERN int
435 lws_get_child_pending_on_writable(const struct lws *wsi);
436 
437 LWS_VISIBLE LWS_EXTERN void
438 lws_clear_child_pending_on_writable(struct lws *wsi);
439 
440 LWS_VISIBLE LWS_EXTERN int
441 lws_get_close_length(struct lws *wsi);
442 
443 LWS_VISIBLE LWS_EXTERN unsigned char *
444 lws_get_close_payload(struct lws *wsi);
445 
456 LWS_VISIBLE LWS_EXTERN
457 struct lws *lws_get_network_wsi(struct lws *wsi);
458 
466 LWS_VISIBLE LWS_EXTERN void
467 lws_set_allocator(void *(*realloc)(void *ptr, size_t size, const char *reason));
468 
469 enum {
470  /*
471  * Flags for enable and disable rxflow with reason bitmap and with
472  * backwards-compatible single bool
473  */
474  LWS_RXFLOW_REASON_USER_BOOL = (1 << 0),
475  LWS_RXFLOW_REASON_HTTP_RXBUFFER = (1 << 6),
476  LWS_RXFLOW_REASON_H2_PPS_PENDING = (1 << 7),
477 
478  LWS_RXFLOW_REASON_APPLIES = (1 << 14),
479  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT = (1 << 13),
480  LWS_RXFLOW_REASON_APPLIES_ENABLE = LWS_RXFLOW_REASON_APPLIES |
481  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT,
482  LWS_RXFLOW_REASON_APPLIES_DISABLE = LWS_RXFLOW_REASON_APPLIES,
483  LWS_RXFLOW_REASON_FLAG_PROCESS_NOW = (1 << 12),
484 
485 };
486 
506 LWS_VISIBLE LWS_EXTERN int
507 lws_rx_flow_control(struct lws *wsi, int enable);
508 
518 LWS_VISIBLE LWS_EXTERN void
519 lws_rx_flow_allow_all_protocol(const struct lws_context *context,
520  const struct lws_protocols *protocol);
521 
541 LWS_VISIBLE LWS_EXTERN size_t
542 lws_remaining_packet_payload(struct lws *wsi);
543 
544 #if defined(LWS_WITH_DIR)
545 
546 typedef enum {
547  LDOT_UNKNOWN,
548  LDOT_FILE,
549  LDOT_DIR,
550  LDOT_LINK,
551  LDOT_FIFO,
552  LDOTT_SOCKET,
553  LDOT_CHAR,
554  LDOT_BLOCK
555 } lws_dir_obj_type_t;
556 
557 struct lws_dir_entry {
558  const char *name;
559  lws_dir_obj_type_t type;
560 };
561 
562 typedef int
563 lws_dir_callback_function(const char *dirpath, void *user,
564  struct lws_dir_entry *lde);
565 
578 LWS_VISIBLE LWS_EXTERN int
579 lws_dir(const char *dirpath, void *user, lws_dir_callback_function cb);
580 #endif
581 
597 size_t lws_get_allocated_heap(void);
598 
605 LWS_VISIBLE LWS_EXTERN int
606 lws_get_tsi(struct lws *wsi);
607 
614 LWS_VISIBLE LWS_EXTERN int
615 lws_is_ssl(struct lws *wsi);
621 LWS_VISIBLE LWS_EXTERN int
622 lws_is_cgi(struct lws *wsi);
623 
634 LWS_VISIBLE LWS_EXTERN int
635 lws_open(const char *__file, int __oflag, ...);
636 
637 struct lws_wifi_scan { /* generic wlan scan item */
638  struct lws_wifi_scan *next;
639  char ssid[32];
640  int32_t rssi; /* divide by .count to get db */
641  uint8_t bssid[6];
642  uint8_t count;
643  uint8_t channel;
644  uint8_t authmode;
645 };
646 
647 #if defined(LWS_WITH_TLS) && !defined(LWS_WITH_MBEDTLS)
648 
654 LWS_VISIBLE LWS_EXTERN SSL*
655 lws_get_ssl(struct lws *wsi);
656 #endif
657 
658 LWS_VISIBLE LWS_EXTERN void
659 lws_explicit_bzero(void *p, size_t len);
660 
661 typedef struct lws_humanize_unit {
662  const char *name; /* array ends with NULL name */
663  uint64_t factor;
665 
666 LWS_VISIBLE LWS_EXTERN const lws_humanize_unit_t humanize_schema_si[7];
667 LWS_VISIBLE LWS_EXTERN const lws_humanize_unit_t humanize_schema_si_bytes[7];
668 LWS_VISIBLE LWS_EXTERN const lws_humanize_unit_t humanize_schema_us[8];
669 
691 LWS_VISIBLE LWS_EXTERN int
692 lws_humanize(char *buf, int len, uint64_t value,
693  const lws_humanize_unit_t *schema);
694 
695 LWS_VISIBLE LWS_EXTERN void
696 lws_ser_wu16be(uint8_t *b, uint16_t u);
697 
698 LWS_VISIBLE LWS_EXTERN void
699 lws_ser_wu32be(uint8_t *b, uint32_t u32);
700 
701 LWS_VISIBLE LWS_EXTERN void
702 lws_ser_wu64be(uint8_t *b, uint64_t u64);
703 
704 LWS_VISIBLE LWS_EXTERN uint16_t
705 lws_ser_ru16be(const uint8_t *b);
706 
707 LWS_VISIBLE LWS_EXTERN uint32_t
708 lws_ser_ru32be(const uint8_t *b);
709 
710 LWS_VISIBLE LWS_EXTERN uint64_t
711 lws_ser_ru64be(const uint8_t *b);
712 
713 LWS_VISIBLE LWS_EXTERN int
714 lws_vbi_encode(uint64_t value, void *buf);
715 
716 LWS_VISIBLE LWS_EXTERN int
717 lws_vbi_decode(const void *buf, uint64_t *value, size_t len);
718 
720 
721 #if defined(LWS_WITH_SPAWN)
722 
723 /* opaque internal struct */
724 struct lws_spawn_piped;
725 
726 typedef void (*lsp_cb_t)(void *opaque, lws_usec_t *accounting, siginfo_t *si,
727  int we_killed_him);
728 
729 
747 struct lws_spawn_piped_info {
748  struct lws_dll2_owner *owner;
749  struct lws_vhost *vh;
750  struct lws *opt_parent;
751 
752  const char * const *exec_array;
753  char **env_array;
754  const char *protocol_name;
755  const char *chroot_path;
756  const char *wd;
757 
758  struct lws_spawn_piped **plsp;
759 
760  void *opaque;
761 
762  lsp_cb_t reap_cb;
763 
764  lws_usec_t timeout_us;
765  int max_log_lines;
766  int tsi;
767 
768  const struct lws_role_ops *ops; /* NULL is raw file */
769 
770  uint8_t disable_ctrlc;
771 };
772 
794 LWS_VISIBLE LWS_EXTERN struct lws_spawn_piped *
795 lws_spawn_piped(const struct lws_spawn_piped_info *lspi);
796 
797 /*
798  * lws_spawn_piped_kill_child_process() - attempt to kill child process
799  *
800  * \p lsp: child object to kill
801  *
802  * Attempts to signal the child process in \p lsp to terminate.
803  */
804 LWS_VISIBLE LWS_EXTERN int
805 lws_spawn_piped_kill_child_process(struct lws_spawn_piped *lsp);
806 
819 LWS_VISIBLE LWS_EXTERN void
820 lws_spawn_stdwsi_closed(struct lws_spawn_piped *lsp);
821 
832 LWS_VISIBLE LWS_EXTERN int
833 lws_spawn_get_stdfd(struct lws *wsi);
834 
835 #endif
836 
837 struct lws_fsmount {
838  const char *layers_path; /* where layers live */
839  const char *overlay_path; /* where overlay instantiations live */
840 
841  char mp[256]; /* mountpoint path */
842  char ovname[64]; /* unique name for mount instance */
843  char distro[64]; /* unique name for layer source */
844 
845 #if defined(__linux__)
846  const char *layers[4]; /* distro layers, like "base", "env" */
847 #endif
848 };
849 
883 LWS_VISIBLE LWS_EXTERN int
884 lws_fsmount_mount(struct lws_fsmount *fsm);
885 
898 LWS_VISIBLE LWS_EXTERN int
899 lws_fsmount_unmount(struct lws_fsmount *fsm);
lws_get_allocated_heap
size_t lws_get_allocated_heap(void)
lws_humanize_unit
Definition: lws-misc.h:661
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_daemonize
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_daemonize(const char *_lock_path)
lws_buflist_describe
LWS_VISIBLE LWS_EXTERN void lws_buflist_describe(struct lws_buflist **head, void *id, const char *reason)
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_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_get_library_version
LWS_VISIBLE const LWS_EXTERN char *LWS_WARN_UNUSED_RESULT lws_get_library_version(void)
lws_cmdline_option
LWS_VISIBLE const LWS_EXTERN char * lws_cmdline_option(int argc, const char **argv, const char *val)
lws_context_creation_info
Definition: lws-context-vhost.h:242
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_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:837
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:637
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))