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 34 /** \defgroup misc Miscellaneous APIs 35 * ##Miscellaneous APIs 36 * 37 * Various APIs outside of other categories 38 */ 39 ///@{ 40 41 struct lws_buflist; 42 43 /** 44 * lws_buflist_append_segment(): add buffer to buflist at head 45 * 46 * \param head: list head 47 * \param buf: buffer to stash 48 * \param len: length of buffer to stash 49 * 50 * Returns -1 on OOM, 1 if this was the first segment on the list, and 0 if 51 * it was a subsequent segment. 52 */ 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); 56 /** 57 * lws_buflist_next_segment_len(): number of bytes left in current segment 58 * 59 * \param head: list head 60 * \param buf: if non-NULL, *buf is written with the address of the start of 61 * the remaining data in the segment 62 * 63 * Returns the number of bytes left in the current segment. 0 indicates 64 * that the buflist is empty (there are no segments on the buflist). 65 */ 66 LWS_VISIBLE LWS_EXTERN size_t 67 lws_buflist_next_segment_len(struct lws_buflist **head, uint8_t **buf); 68 69 /** 70 * lws_buflist_use_segment(): remove len bytes from the current segment 71 * 72 * \param head: list head 73 * \param len: number of bytes to mark as used 74 * 75 * If len is less than the remaining length of the current segment, the position 76 * in the current segment is simply advanced and it returns. 77 * 78 * If len uses up the remaining length of the current segment, then the segment 79 * is deleted and the list head moves to the next segment if any. 80 * 81 * Returns the number of bytes left in the current segment. 0 indicates 82 * that the buflist is empty (there are no segments on the buflist). 83 */ 84 LWS_VISIBLE LWS_EXTERN size_t 85 lws_buflist_use_segment(struct lws_buflist **head, size_t len); 86 87 /** 88 * lws_buflist_total_len(): Get the total size of the buflist 89 * 90 * \param head: list head 91 * 92 * Returns the total number of bytes held on all segments of the buflist 93 */ 94 LWS_VISIBLE LWS_EXTERN size_t 95 lws_buflist_total_len(struct lws_buflist **head); 96 97 /** 98 * lws_buflist_linear_copy(): copy everything out as one without consuming 99 * 100 * \param head: list head 101 * \param ofs: start offset into buflist in bytes 102 * \param buf: buffer to copy linearly into 103 * \param len: length of buffer available 104 * 105 * Returns -1 if len is too small, or bytes copied. Happy to do partial 106 * copies, returns 0 when there are no more bytes to copy. 107 */ 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 112 /** 113 * lws_buflist_destroy_all_segments(): free all segments on the list 114 * 115 * \param head: list head 116 * 117 * This frees everything on the list unconditionally. *head is always 118 * NULL after this. 119 */ 120 LWS_VISIBLE LWS_EXTERN void 121 lws_buflist_destroy_all_segments(struct lws_buflist **head); 122 123 /** 124 * lws_buflist_describe(): debug helper logging buflist status 125 * 126 * \param head: list head 127 * \param id: pointer shown in debug list 128 * \param reason: reason string show in debug list 129 * 130 * Iterates through the buflist segments showing position and size. 131 * This only exists when lws was built in debug mode 132 */ 133 LWS_VISIBLE LWS_EXTERN void 134 lws_buflist_describe(struct lws_buflist **head, void *id, const char *reason); 135 136 /** 137 * lws_ptr_diff(): helper to report distance between pointers as an int 138 * 139 * \param head: the pointer with the larger address 140 * \param tail: the pointer with the smaller address 141 * 142 * This helper gives you an int representing the number of bytes further 143 * forward the first pointer is compared to the second pointer. 144 */ 145 #define lws_ptr_diff(head, tail) \ 146 ((int)((char *)(head) - (char *)(tail))) 147 148 /** 149 * lws_snprintf(): snprintf that truncates the returned length too 150 * 151 * \param str: destination buffer 152 * \param size: bytes left in destination buffer 153 * \param format: format string 154 * \param ...: args for format 155 * 156 * This lets you correctly truncate buffers by concatenating lengths, if you 157 * reach the limit the reported length doesn't exceed the limit. 158 */ 159 LWS_VISIBLE LWS_EXTERN int 160 lws_snprintf(char *str, size_t size, const char *format, ...) LWS_FORMAT(3); 161 162 /** 163 * lws_strncpy(): strncpy that guarantees NUL on truncated copy 164 * 165 * \param dest: destination buffer 166 * \param src: source buffer 167 * \param size: bytes left in destination buffer 168 * 169 * This lets you correctly truncate buffers by concatenating lengths, if you 170 * reach the limit the reported length doesn't exceed the limit. 171 */ 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 183 /** 184 * lws_hex_to_byte_array(): convert hex string like 0123456789ab into byte data 185 * 186 * \param h: incoming NUL-terminated hex string 187 * \param dest: array to fill with binary decodes of hex pairs from h 188 * \param max: maximum number of bytes dest can hold, must be at least half 189 * the size of strlen(h) 190 * 191 * This converts hex strings into an array of 8-bit representations, ie the 192 * input "abcd" produces two bytes of value 0xab and 0xcd. 193 * 194 * Returns number of bytes produced into \p dest, or -1 on error. 195 * 196 * Errors include non-hex chars and an odd count of hex chars in the input 197 * string. 198 */ 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 218 /** 219 * lws_get_random(): fill a buffer with platform random data 220 * 221 * \param context: the lws context 222 * \param buf: buffer to fill 223 * \param len: how much to fill 224 * 225 * Fills buf with len bytes of random. Returns the number of bytes set, if 226 * not equal to len, then getting the random failed. 227 */ 228 LWS_VISIBLE LWS_EXTERN size_t 229 lws_get_random(struct lws_context *context, void *buf, size_t len); 230 /** 231 * lws_daemonize(): make current process run in the background 232 * 233 * \param _lock_path: the filepath to write the lock file 234 * 235 * Spawn lws as a background process, taking care of various things 236 */ 237 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 238 lws_daemonize(const char *_lock_path); 239 /** 240 * lws_get_library_version(): return string describing the version of lws 241 * 242 * On unix, also includes the git describe 243 */ 244 LWS_VISIBLE LWS_EXTERN const char * LWS_WARN_UNUSED_RESULT 245 lws_get_library_version(void); 246 247 /** 248 * lws_wsi_user() - get the user data associated with the connection 249 * \param wsi: lws connection 250 * 251 * Not normally needed since it's passed into the callback 252 */ 253 LWS_VISIBLE LWS_EXTERN void * 254 lws_wsi_user(struct lws *wsi); 255 256 /** 257 * lws_set_wsi_user() - set the user data associated with the client connection 258 * \param wsi: lws connection 259 * \param user: user data 260 * 261 * By default lws allocates this and it's not legal to externally set it 262 * yourself. However client connections may have it set externally when the 263 * connection is created... if so, this api can be used to modify it at 264 * runtime additionally. 265 */ 266 LWS_VISIBLE LWS_EXTERN void 267 lws_set_wsi_user(struct lws *wsi, void *user); 268 269 /** 270 * lws_parse_uri: cut up prot:/ads:port/path into pieces 271 * Notice it does so by dropping '\0' into input string 272 * and the leading / on the path is consequently lost 273 * 274 * \param p: incoming uri string.. will get written to 275 * \param prot: result pointer for protocol part (https://) 276 * \param ads: result pointer for address part 277 * \param port: result pointer for port part 278 * \param path: result pointer for path part 279 * 280 * You may also refer to unix socket addresses, using a '+' at the start of 281 * the address. In this case, the address should end with ':', which is 282 * treated as the separator between the address and path (the normal separator 283 * '/' is a valid part of the socket path). Eg, 284 * 285 * http://+/var/run/mysocket:/my/path 286 * 287 * If the first character after the + is '@', it's interpreted by lws client 288 * processing as meaning to use linux abstract namespace sockets, the @ is 289 * replaced with a '\0' before use. 290 */ 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); 294 /** 295 * lws_cmdline_option(): simple commandline parser 296 * 297 * \param argc: count of argument strings 298 * \param argv: argument strings 299 * \param val: string to find 300 * 301 * Returns NULL if the string \p val is not found in the arguments. 302 * 303 * If it is found, then it returns a pointer to the next character after \p val. 304 * So if \p val is "-d", then for the commandlines "myapp -d15" and 305 * "myapp -d 15", in both cases the return will point to the "15". 306 * 307 * In the case there is no argument, like "myapp -d", the return will 308 * either point to the '\\0' at the end of -d, or to the start of the 309 * next argument, ie, will be non-NULL. 310 */ 311 LWS_VISIBLE LWS_EXTERN const char * 312 lws_cmdline_option(int argc, const char **argv, const char *val); 313 314 /** 315 * lws_cmdline_option_handle_builtin(): apply standard cmdline options 316 * 317 * \param argc: count of argument strings 318 * \param argv: argument strings 319 * \param info: context creation info 320 * 321 * Applies standard options to the context creation info to save them having 322 * to be (unevenly) copied into the minimal examples. 323 * 324 * Applies default log levels that can be overriden by -d 325 */ 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 330 /** 331 * lws_now_secs(): return seconds since 1970-1-1 332 */ 333 LWS_VISIBLE LWS_EXTERN unsigned long 334 lws_now_secs(void); 335 336 /** 337 * lws_now_usecs(): return useconds since 1970-1-1 338 */ 339 LWS_VISIBLE LWS_EXTERN lws_usec_t 340 lws_now_usecs(void); 341 342 /** 343 * lws_get_context - Allow getting lws_context from a Websocket connection 344 * instance 345 * 346 * With this function, users can access context in the callback function. 347 * Otherwise users may have to declare context as a global variable. 348 * 349 * \param wsi: Websocket connection instance 350 */ 351 LWS_VISIBLE LWS_EXTERN struct lws_context * LWS_WARN_UNUSED_RESULT 352 lws_get_context(const struct lws *wsi); 353 354 /** 355 * lws_get_vhost_listen_port - Find out the port number a vhost is listening on 356 * 357 * In the case you passed 0 for the port number at context creation time, you 358 * can discover the port number that was actually chosen for the vhost using 359 * this api. 360 * 361 * \param vhost: Vhost to get listen port from 362 */ 363 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 364 lws_get_vhost_listen_port(struct lws_vhost *vhost); 365 366 /** 367 * lws_get_count_threads(): how many service threads the context uses 368 * 369 * \param context: the lws context 370 * 371 * By default this is always 1, if you asked for more than lws can handle it 372 * will clip the number of threads. So you can use this to find out how many 373 * threads are actually in use. 374 */ 375 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 376 lws_get_count_threads(struct lws_context *context); 377 378 /** 379 * lws_get_parent() - get parent wsi or NULL 380 * \param wsi: lws connection 381 * 382 * Specialized wsi like cgi stdin/out/err are associated to a parent wsi, 383 * this allows you to get their parent. 384 */ 385 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT 386 lws_get_parent(const struct lws *wsi); 387 388 /** 389 * lws_get_child() - get child wsi or NULL 390 * \param wsi: lws connection 391 * 392 * Allows you to find a related wsi from the parent wsi. 393 */ 394 LWS_VISIBLE LWS_EXTERN struct lws * LWS_WARN_UNUSED_RESULT 395 lws_get_child(const struct lws *wsi); 396 397 /** 398 * lws_get_effective_uid_gid() - find out eventual uid and gid while still root 399 * 400 * \param context: lws context 401 * \param uid: pointer to uid result 402 * \param gid: pointer to gid result 403 * 404 * This helper allows you to find out what the uid and gid for the process will 405 * be set to after the privileges are dropped, beforehand. So while still root, 406 * eg in LWS_CALLBACK_PROTOCOL_INIT, you can arrange things like cache dir 407 * and subdir creation / permissions down /var/cache dynamically. 408 */ 409 LWS_VISIBLE LWS_EXTERN void 410 lws_get_effective_uid_gid(struct lws_context *context, int *uid, int *gid); 411 412 /** 413 * lws_get_udp() - get wsi's udp struct 414 * 415 * \param wsi: lws connection 416 * 417 * Returns NULL or pointer to the wsi's UDP-specific information 418 */ 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 446 /** 447 * lws_get_network_wsi() - Returns wsi that has the tcp connection for this wsi 448 * 449 * \param wsi: wsi you have 450 * 451 * Returns wsi that has the tcp connection (which may be the incoming wsi) 452 * 453 * HTTP/1 connections will always return the incoming wsi 454 * HTTP/2 connections may return a different wsi that has the tcp connection 455 */ 456 LWS_VISIBLE LWS_EXTERN 457 struct lws *lws_get_network_wsi(struct lws *wsi); 458 459 /** 460 * lws_set_allocator() - custom allocator support 461 * 462 * \param realloc 463 * 464 * Allows you to replace the allocator (and deallocator) used by lws 465 */ 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 487 /** 488 * lws_rx_flow_control() - Enable and disable socket servicing for 489 * received packets. 490 * 491 * If the output side of a server process becomes choked, this allows flow 492 * control for the input side. 493 * 494 * \param wsi: Websocket connection instance to get callback for 495 * \param enable: 0 = disable read servicing for this connection, 1 = enable 496 * 497 * If you need more than one additive reason for rxflow control, you can give 498 * iLWS_RXFLOW_REASON_APPLIES_ENABLE or _DISABLE together with one or more of 499 * b5..b0 set to idicate which bits to enable or disable. If any bits are 500 * enabled, rx on the connection is suppressed. 501 * 502 * LWS_RXFLOW_REASON_FLAG_PROCESS_NOW flag may also be given to force any change 503 * in rxflowbstatus to benapplied immediately, this should be used when you are 504 * changing a wsi flow control state from outside a callback on that wsi. 505 */ 506 LWS_VISIBLE LWS_EXTERN int 507 lws_rx_flow_control(struct lws *wsi, int enable); 508 509 /** 510 * lws_rx_flow_allow_all_protocol() - Allow all connections with this protocol to receive 511 * 512 * When the user server code realizes it can accept more input, it can 513 * call this to have the RX flow restriction removed from all connections using 514 * the given protocol. 515 * \param context: lws_context 516 * \param protocol: all connections using this protocol will be allowed to receive 517 */ 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 522 /** 523 * lws_remaining_packet_payload() - Bytes to come before "overall" 524 * rx fragment is complete 525 * \param wsi: Websocket instance (available from user callback) 526 * 527 * This tracks how many bytes are left in the current ws fragment, according 528 * to the ws length given in the fragment header. 529 * 530 * If the message was in a single fragment, and there is no compression, this 531 * is the same as "how much data is left to read for this message". 532 * 533 * However, if the message is being sent in multiple fragments, this will 534 * reflect the unread amount of the current **fragment**, not the message. With 535 * ws, it is legal to not know the length of the message before it completes. 536 * 537 * Additionally if the message is sent via the negotiated permessage-deflate 538 * extension, this number only tells the amount of **compressed** data left to 539 * be read, since that is the only information available at the ws layer. 540 */ 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 566 /** 567 * lws_dir() - get a callback for everything in a directory 568 * 569 * \param dirpath: the directory to scan 570 * \param user: pointer to give to callback 571 * \param cb: callback to receive information on each file or dir 572 * 573 * Calls \p cb (with \p user) for every object in dirpath. 574 * 575 * This wraps whether it's using POSIX apis, or libuv (as needed for windows, 576 * since it refuses to support POSIX apis for this). 577 */ 578 LWS_VISIBLE LWS_EXTERN int 579 lws_dir(const char *dirpath, void *user, lws_dir_callback_function cb); 580 #endif 581 582 /** 583 * lws_get_allocated_heap() - if the platform supports it, returns amount of 584 * heap allocated by lws itself 585 * 586 * On glibc currently, this reports the total amount of current logical heap 587 * allocation, found by tracking the amount allocated by lws_malloc() and 588 * friends and accounting for freed allocations via lws_free(). 589 * 590 * This is useful for confirming where processwide heap allocations actually 591 * come from... this number represents all lws internal allocations, for 592 * fd tables, wsi allocations, ah, etc combined. It doesn't include allocations 593 * from user code, since lws_malloc() etc are not exported from the library. 594 * 595 * On other platforms, it always returns 0. 596 */ 597 size_t lws_get_allocated_heap(void); 598 599 /** 600 * lws_get_tsi() - Get thread service index wsi belong to 601 * \param wsi: websocket connection to check 602 * 603 * Returns more than zero (or zero if only one service thread as is the default). 604 */ 605 LWS_VISIBLE LWS_EXTERN int 606 lws_get_tsi(struct lws *wsi); 607 608 /** 609 * lws_is_ssl() - Find out if connection is using SSL 610 * \param wsi: websocket connection to check 611 * 612 * Returns nonzero if the wsi is inside a tls tunnel, else zero. 613 */ 614 LWS_VISIBLE LWS_EXTERN int 615 lws_is_ssl(struct lws *wsi); 616 /** 617 * lws_is_cgi() - find out if this wsi is running a cgi process 618 * 619 * \param wsi: lws connection 620 */ 621 LWS_VISIBLE LWS_EXTERN int 622 lws_is_cgi(struct lws *wsi); 623 624 /** 625 * lws_open() - platform-specific wrapper for open that prepares the fd 626 * 627 * \param __file: the filepath to open 628 * \param __oflag: option flags 629 * 630 * This is a wrapper around platform open() that sets options on the fd 631 * according to lws policy. Currently that is FD_CLOEXEC to stop the opened 632 * fd being available to any child process forked by user code. 633 */ 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 /** 649 * lws_get_ssl() - Return wsi's SSL context structure 650 * \param wsi: websocket connection 651 * 652 * Returns pointer to the SSL library's context structure 653 */ 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; 664 } lws_humanize_unit_t; 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 670 /** 671 * lws_humanize() - Convert possibly large number to human-readable uints 672 * 673 * \param buf: result string buffer 674 * \param len: remaining length in \p buf 675 * \param value: the uint64_t value to represent 676 * \param schema: and array of scaling factors and units 677 * 678 * This produces a concise string representation of \p value, referencing the 679 * schema \p schema of scaling factors and units to find the smallest way to 680 * render it. 681 * 682 * Three schema are exported from lws for general use, humanize_schema_si, which 683 * represents as, eg, " 22.130Gi" or " 128 "; humanize_schema_si_bytes 684 * which is the same but shows, eg, " 22.130GiB", and humanize_schema_us, 685 * which represents a count of us as a human-readable time like " 14.350min", 686 * or " 1.500d". 687 * 688 * You can produce your own schema. 689 */ 690 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 719 ///@} 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 730 /** 731 * lws_spawn_piped_info - details given to create a spawned pipe 732 * 733 * \p owner: lws_dll2_owner_t that lists all active spawns, or NULL 734 * \p vh: vhost to bind stdwsi to... from opt_parent if given 735 * \p opt_parent: optional parent wsi for stdwsi 736 * \p exec_array: argv for process to spawn 737 * \p env_array: environment for spawned process, NULL ends env list 738 * \p protocol_name: NULL, or vhost protocol name to bind stdwsi to 739 * \p chroot_path: NULL, or chroot patch for child process 740 * \p wd: working directory to cd to after fork, NULL defaults to /tmp 741 * \p plsp: NULL, or pointer to the outer lsp pointer so it can be set NULL when destroyed 742 * \p opaque: pointer passed to the reap callback, if any 743 * \p timeout: optional us-resolution timeout, or zero 744 * \p reap_cb: callback when child process has been reaped and the lsp destroyed 745 * \p tsi: tsi to bind stdwsi to... from opt_parent if given 746 */ 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 773 /** 774 * lws_spawn_piped() - spawn a child process with stdxxx redirected 775 * 776 * \p lspi: info struct describing details of spawn to create 777 * 778 * This spawns a child process managed in the lsp object and with attributes 779 * set in the arguments. The stdin/out/err streams are redirected to pipes 780 * which are instantiated into wsi that become child wsi of \p parent if non- 781 * NULL. .opaque_user_data on the stdwsi created is set to point to the 782 * lsp object, so this can be recovered easily in the protocol handler. 783 * 784 * If \p owner is non-NULL, successful spawns join the given dll2 owner in the 785 * original process. 786 * 787 * If \p timeout is non-zero, successful spawns register a sul with the us- 788 * resolution timeout to callback \p timeout_cb, in the original process. 789 * 790 * Returns 0 if the spawn went OK or nonzero if it failed and was cleaned up. 791 * The spawned process continues asynchronously and this will return after 792 * starting it if all went well. 793 */ 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 807 /** 808 * lws_spawn_stdwsi_closed() - inform the spawn one of its stdxxx pipes closed 809 * 810 * \p lsp: the spawn object 811 * 812 * When you notice one of the spawn stdxxx pipes closed, inform the spawn 813 * instance using this api. When it sees all three have closed, it will 814 * automatically try to reap the child process. 815 * 816 * This is the mechanism whereby the spawn object can understand its child 817 * has closed. 818 */ 819 LWS_VISIBLE LWS_EXTERN void 820 lws_spawn_stdwsi_closed(struct lws_spawn_piped *lsp); 821 822 /** 823 * lws_spawn_get_stdfd() - return std channel index for stdwsi 824 * 825 * \p wsi: the wsi 826 * 827 * If you know wsi is a stdwsi from a spawn, you can determine its original 828 * channel index / fd before the pipes replaced the default fds. It will return 829 * one of 0 (STDIN), 1 (STDOUT) or 2 (STDERR). You can handle all three in the 830 * same protocol handler and then disambiguate them using this api. 831 */ 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 850 /** 851 * lws_fsmount_mount() - Mounts an overlayfs stack of layers 852 * 853 * \p fsm: struct lws_fsmount specifying the mount layout 854 * 855 * This api is able to assemble up to 4 layer directories on to a mountpoint 856 * using overlayfs mount (Linux only). 857 * 858 * Set fsm.layers_path to the base dir where the layers themselves live, the 859 * entries in fsm.layers[] specifies the relative path to the layer, comprising 860 * fsm.layers_path/fsm.distro/fsm.layers[], with [0] being the deepest, earliest 861 * layer and the rest being progressively on top of [0]; NULL indicates the 862 * layer is unused. 863 * 864 * fsm.overlay_path is the base path of the overlayfs instantiations... empty 865 * dirs must exist at 866 * 867 * fsm.overlay_path/overlays/fsm.ovname/work 868 * fsm.overlay_path/overlays/fsm.ovname/session 869 * 870 * Set fsm.mp to the path of an already-existing empty dir that will be the 871 * mountpoint, this can be whereever you like. 872 * 873 * Overlayfs merges the union of all the contributing layers at the mountpoint, 874 * the mount is writeable but the layer themselves are immutable, all additions 875 * and changes are stored in 876 * 877 * fsm.overlay_path/overlays/fsm.ovname/session 878 * 879 * Returns 0 if mounted OK, nonzero if errors. 880 * 881 * Retain fsm for use with unmounting. 882 */ 883 LWS_VISIBLE LWS_EXTERN int 884 lws_fsmount_mount(struct lws_fsmount *fsm); 885 886 /** 887 * lws_fsmount_unmount() - Unmounts an overlayfs dir 888 * 889 * \p fsm: struct lws_fsmount specifying the mount layout 890 * 891 * Unmounts the mountpoint in fsm.mp. 892 * 893 * Delete fsm.overlay_path/overlays/fsm.ovname/session to permanently eradicate 894 * all changes from the time the mountpoint was in use. 895 * 896 * Returns 0 if unmounted OK. 897 */ 898 LWS_VISIBLE LWS_EXTERN int 899 lws_fsmount_unmount(struct lws_fsmount *fsm); 900