4 There's a helper api `lws_daemonize` built by default that does everything you
5 need to daemonize well, including creating a lock file. If you're making
6 what's basically a daemon, just call this early in your init to fork to a
7 headless background process and exit the starting process.
9 Notice stdout, stderr, stdin are all redirected to /dev/null to enforce your
10 daemon is headless, so you'll need to sort out alternative logging, by, eg,
14 Maximum number of connections
15 -----------------------------
17 The maximum number of connections the library can deal with is decided when
18 it starts by querying the OS to find out how many file descriptors it is
19 allowed to open (1024 on Fedora for example). It then allocates arrays that
20 allow up to that many connections, minus whatever other file descriptors are
21 in use by the user code.
23 If you want to restrict that allocation, or increase it, you can use ulimit or
24 similar to change the avaiable number of file descriptors, and when restarted
25 **libwebsockets** will adapt accordingly.
28 Libwebsockets is singlethreaded
29 -------------------------------
31 Directly performing websocket actions from other threads is not allowed.
32 Aside from the internal data being inconsistent in `forked()` processes,
33 the scope of a `wsi` (`struct websocket`) can end at any time during service
34 with the socket closing and the `wsi` freed.
36 Websocket write activities should only take place in the
37 `LWS_CALLBACK_SERVER_WRITEABLE` callback as described below.
39 Only live connections appear in the user callbacks, so this removes any
40 possibility of trying to used closed and freed wsis.
42 If you need to service other socket or file descriptors as well as the
43 websocket ones, you can combine them together with the websocket ones
44 in one poll loop, see "External Polling Loop support" below, and
45 still do it all in one thread / process context.
48 Only send data when socket writeable
49 ------------------------------------
51 You should only send data on a websocket connection from the user callback
52 `LWS_CALLBACK_SERVER_WRITEABLE` (or `LWS_CALLBACK_CLIENT_WRITEABLE` for
55 If you want to send something, do not just send it but request a callback
56 when the socket is writeable using
58 - `libwebsocket_callback_on_writable(context, wsi)`` for a specific `wsi`, or
59 - `libwebsocket_callback_on_writable_all_protocol(protocol)` for all connections
60 using that protocol to get a callback when next writeable.
62 Usually you will get called back immediately next time around the service
63 loop, but if your peer is slow or temporarily inactive the callback will be
64 delayed accordingly. Generating what to write and sending it should be done
65 in the ...WRITEABLE callback.
67 See the test server code for an example of how to do this.
70 Do not rely on only your own WRITEABLE requests appearing
71 ---------------------------------------------------------
73 Libwebsockets may generate additional `LWS_CALLBACK_CLIENT_WRITEABLE` events
74 if it met network conditions where it had to buffer your send data internally.
76 So your code for `LWS_CALLBACK_CLIENT_WRITEABLE` needs to own the decision
77 about what to send, it can't assume that just because the writeable callback
78 came it really is time to send something.
80 It's quite possible you get an 'extra' writeable callback at any time and
81 just need to `return 0` and wait for the expected callback later.
84 Closing connections from the user side
85 --------------------------------------
87 When you want to close a connection, you do it by returning `-1` from a
88 callback for that connection.
90 You can provoke a callback by calling `libwebsocket_callback_on_writable` on
91 the wsi, then notice in the callback you want to close it and just return -1.
92 But usually, the decision to close is made in a callback already and returning
95 If the socket knows the connection is dead, because the peer closed or there
96 was an affirmitive network error like a FIN coming, then **libwebsockets** will
97 take care of closing the connection automatically.
99 If you have a silently dead connection, it's possible to enter a state where
100 the send pipe on the connection is choked but no ack will ever come, so the
101 dead connection will never become writeable. To cover that, you can use TCP
102 keepalives (see later in this document)
108 To support fragmented messages you need to check for the final
109 frame of a message with `libwebsocket_is_final_fragment`. This
110 check can be combined with `libwebsockets_remaining_packet_payload`
111 to gather the whole contents of a message, eg:
114 case LWS_CALLBACK_RECEIVE:
116 Client * const client = (Client *)user;
117 const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
119 if (!remaining && libwebsocket_is_final_fragment(wsi)) {
120 if (client->HasFragments()) {
121 client->AppendMessageFragment(in, len, 0);
122 in = (void *)client->GetMessage();
123 len = client->GetMessageLength();
126 client->ProcessMessage((char *)in, len, wsi);
127 client->ResetMessage();
129 client->AppendMessageFragment(in, len, remaining);
134 The test app libwebsockets-test-fraggle sources also show how to
135 deal with fragmented messages.
141 Also using `lws_set_log_level` api you may provide a custom callback to actually
142 emit the log string. By default, this points to an internal emit function
143 that sends to stderr. Setting it to `NULL` leaves it as it is instead.
145 A helper function `lwsl_emit_syslog()` is exported from the library to simplify
146 logging to syslog. You still need to use `setlogmask`, `openlog` and `closelog`
149 The logging apis are made available for user code.
157 The difference between notice and info is that notice will be logged by default
158 whereas info is ignored by default.
161 External Polling Loop support
162 -----------------------------
164 **libwebsockets** maintains an internal `poll()` array for all of its
165 sockets, but you can instead integrate the sockets into an
166 external polling array. That's needed if **libwebsockets** will
167 cooperate with an existing poll array maintained by another
170 Four callbacks `LWS_CALLBACK_ADD_POLL_FD`, `LWS_CALLBACK_DEL_POLL_FD`,
171 `LWS_CALLBACK_SET_MODE_POLL_FD` and `LWS_CALLBACK_CLEAR_MODE_POLL_FD`
172 appear in the callback for protocol 0 and allow interface code to
173 manage socket descriptors in other poll loops.
175 You can pass all pollfds that need service to `libwebsocket_service_fd()`, even
176 if the socket or file does not belong to **libwebsockets** it is safe.
178 If **libwebsocket** handled it, it zeros the pollfd `revents` field before returning.
179 So you can let **libwebsockets** try and if `pollfd->revents` is nonzero on return,
180 you know it needs handling by your code.
183 Using with in c++ apps
184 ----------------------
186 The library is ready for use by C++ apps. You can get started quickly by
187 copying the test server
190 $ cp test-server/test-server.c test.cpp
193 and building it in C++ like this
196 $ g++ -DINSTALL_DATADIR=\"/usr/share\" -ocpptest test.cpp -lwebsockets
199 `INSTALL_DATADIR` is only needed because the test server uses it as shipped, if
200 you remove the references to it in your app you don't need to define it on
204 Availability of header information
205 ----------------------------------
207 From v1.2 of the library onwards, the HTTP header content is `free()`d as soon
208 as the websocket connection is established. For websocket servers, you can
209 copy interesting headers by handling `LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION`
210 callback, for clients there's a new callback just for this purpose
211 `LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH`.
217 It is possible for a connection which is not being used to send to die
218 silently somewhere between the peer and the side not sending. In this case
219 by default TCP will just not report anything and you will never get any more
220 incoming data or sign the link is dead until you try to send.
222 To deal with getting a notification of that situation, you can choose to
223 enable TCP keepalives on all **libwebsockets** sockets, when you create the
226 To enable keepalive, set the ka_time member of the context creation parameter
227 struct to a nonzero value (in seconds) at context creation time. You should
228 also fill ka_probes and ka_interval in that case.
230 With keepalive enabled, the TCP layer will send control packets that should
231 stimulate a response from the peer without affecting link traffic. If the
232 response is not coming, the socket will announce an error at `poll()` forcing
235 Note that BSDs don't support keepalive time / probes / interval per-socket
236 like Linux does. On those systems you can enable keepalive by a nonzero
237 value in `ka_time`, but the systemwide kernel settings for the time / probes/
238 interval are used, regardless of what nonzero value is in `ka_time`.
240 Optimizing SSL connections
241 --------------------------
243 There's a member `ssl_cipher_list` in the `lws_context_creation_info` struct
244 which allows the user code to restrict the possible cipher selection at
245 context-creation time.
247 You might want to look into that to stop the ssl peers selecting a cipher which
248 is too computationally expensive. To use it, point it to a string like
250 `"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"`
252 if left `NULL`, then the "DEFAULT" set of ciphers are all possible to select.
255 Async nature of client connections
256 ----------------------------------
258 When you call `libwebsocket_client_connect(..)` and get a `wsi` back, it does not
259 mean your connection is active. It just mean it started trying to connect.
261 Your client connection is actually active only when you receive
262 `LWS_CALLBACK_CLIENT_ESTABLISHED` for it.
264 There's a 5 second timeout for the connection, and it may give up or die for
265 other reasons, if any of that happens you'll get a
266 `LWS_CALLBACK_CLIENT_CONNECTION_ERROR` callback on protocol 0 instead for the
269 After attempting the connection and getting back a non-`NULL` `wsi` you should
270 loop calling `libwebsocket_service()` until one of the above callbacks occurs.
272 As usual, see [test-client.c](test-server/test-client.c) for example code.