Subject: [PATCH] Nicer readmes using markdown.
This is still readable in raw text, but much nicer for github with heading and syntax highlighting and such.
diff --git a/README.build b/README.build.md
similarity index 69%
rename from README.build
rename to README.build.md
index 5521e06..00a2702 100644
--- a/README.build
+++ b/README.build.md
@@ -4,9 +4,9 @@
CMake is a multi-platform build tool that can generate build files for many
different target platforms. See more info at http://www.cmake.org
-CMake also allows/recommends you to do "out of source"-builds, that is,
-the build files are separated from your sources, so there is no need to
-create elaborate clean scripts to get a clean source tree, instead you
+CMake also allows/recommends you to do "out of source"-builds, that is,
+the build files are separated from your sources, so there is no need to
+create elaborate clean scripts to get a clean source tree, instead you
simply remove your build directory.
Libwebsockets has been tested to build successfully on the following platforms
@@ -21,7 +21,7 @@
----------------------------------
The project settings used by CMake to generate the platform specific build
-files is called CMakeLists.txt. CMake then uses one of its "Generators" to
+files is called [CMakeLists.txt](CMakeLists.txt). CMake then uses one of its "Generators" to
output a Visual Studio project or Make file for instance. To see a list of
the available generators for your platform, simply run the "cmake" command.
@@ -38,48 +38,60 @@
3. Generate the build files (default is Make files):
- cd /path/to/src
- mkdir build
- cd build
- cmake ..
+ ```bash
+ $ cd /path/to/src
+ $ mkdir build
+ $ cd build
+ $ cmake ..
+ ```
- (NOTE: The build/ directory can have any name and be located anywhere
- on your filesystem, and that the argument ".." given to cmake is simply
- the source directory of libwebsockets containing the CMakeLists.txt
+ (**NOTE**: The `build/`` directory can have any name and be located anywhere
+ on your filesystem, and that the argument `..` given to cmake is simply
+ the source directory of **libwebsockets** containing the [CMakeLists.txt](CMakeLists.txt)
project file. All examples in this file assumes you use "..")
- NOTE2
+ **NOTE2**:
A common option you may want to give is to set the install path, same
as --prefix= with autotools. It defaults to /usr/local.
You can do this by, eg
- cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
+ ```bash
+ $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
+ ```
- NOTE3
+ **NOTE3**:
On machines that want libraries in lib64, you can also add the
following to the cmake line
- -DLIB_SUFFIX=64
-
- NOTE4
+ ```bash
+ -DLIB_SUFFIX=64
+ ```
+
+ **NOTE4**:
If you are building against a non-distro OpenSSL (eg, in order to get
access to ALPN support only in newer OpenSSL versions) the nice way to
express that in one cmake command is eg,
-
- cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
+
+ ```bash
+ $ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
-DCMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE=/usr/local/ssl \
-DLWS_WITH_HTTP2=1
-
+ ```
+
When you run the test apps using non-distro SSL, you have to force them
to use your libs, not the distro ones
-
- LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
+
+ ```bash
+ $ LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
+ ```
4. Finally you can build using the generated Makefile:
- make
+ ```bash
+ $ make
+ ```
-
+
Quirk of cmake
--------------
@@ -97,15 +109,17 @@
3. Generate the Visual studio project by opening the Visual Studio cmd prompt:
+ ```bash
cd <path to src>
md build
cd build
cmake -G "Visual Studio 10" ..
+ ```
- (NOTE: There is also a cmake-gui available on Windows if you prefer that)
+ (**NOTE**: There is also a cmake-gui available on Windows if you prefer that)
4. Now you should have a generated Visual Studio Solution in your
- <path to src>/build directory, which can be used to build.
+ `<path to src>/build` directory, which can be used to build.
Setting compile options
-----------------------
@@ -129,7 +143,7 @@
--------
If you have a curses enabled build you simply type:
(not all packages include this, my debian install does not for example).
-
+
ccmake
Windows GUI
@@ -145,17 +159,19 @@
It contains a OpenSSL compatability layer which makes it possible to pretty
much link to it instead of OpenSSL, giving a much smaller footprint.
-NOTE: cyassl needs to be compiled using the --enable-opensslextra flag for
+**NOTE**: cyassl needs to be compiled using the `--enable-opensslextra` flag for
this to work.
Compiling libwebsockets with CyaSSL
-----------------------------------
+```bash
cmake .. -DLWS_USE_CYASSL=1 \
-DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
-DLWS_CYASSL_LIB=/path/to/cyassl/cyassl.a ..
+```
-NOTE: On windows use the .lib file extension for LWS_CYASSL_LIB instead.
+**NOTE**: On windows use the .lib file extension for `LWS_CYASSL_LIB` instead.
Reproducing HTTP2.0 tests
@@ -165,41 +181,48 @@
ALPN / NPN. Most distros still have older versions. You'll know it's right by
seeing
+```bash
lwsts[4752]: Compiled with OpenSSL support
lwsts[4752]: Using SSL mode
lwsts[4752]: HTTP2 / ALPN enabled
+```
at lws startup.
For non-SSL HTTP2.0 upgrade
-nghttp -nvasu http://localhost:7681/test.htm
+```bash
+$ nghttp -nvasu http://localhost:7681/test.htm
+```
For SSL / ALPN HTTP2.0 upgrade
-nghttp -nvas https://localhost:7681/test.html
-
+```
+$ nghttp -nvas https://localhost:7681/test.html
+```
Cross compiling
---------------
-To enable cross compiling libwebsockets using CMake you need to create
+To enable cross compiling **libwebsockets** using CMake you need to create
a "Toolchain file" that you supply to CMake when generating your build files.
CMake will then use the cross compilers and build paths specified in this file
to look for dependencies and such.
-Libwebsockets includes an example toolchain file cross-arm-linux-gnueabihf.cmake
+**Libwebsockets** includes an example toolchain file [cross-arm-linux-gnueabihf.cmake](cross-arm-linux-gnueabihf.cmake)
you can use as a starting point.
The commandline to configure for cross with this would look like
-cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
+```bash
+$ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
-DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \
-DWITHOUT_EXTENSIONS=1 -DWITH_SSL=0
+```
The example shows how to build with no external cross lib dependencies, you
-need to proide the cross libraries otherwise.
+need to provide the cross libraries otherwise.
-NOTE: start from an EMPTY build directory if you had a non-cross build in there
+**NOTE**: start from an EMPTY build directory if you had a non-cross build in there
before the settings will be cached and your changes ignored.
Additional information on cross compilation with CMake:
@@ -215,13 +238,15 @@
Update at 8dac94d (2013-02-18)
-./configure --without-client --without-extensions --disable-debug --without-daemonize
+```bash
+$ ./configure --without-client --without-extensions --disable-debug --without-daemonize
Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd)
Per-connection [3]: 72 bytes, +1328 during headers
.text .rodata .data .bss
11512 2784 288 4
+```
This shows the impact of the major configuration with/without options at
13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
@@ -231,25 +256,24 @@
the right idea for relative "expense" of features.
Static allocations, ARM9
- .text .rodata .data .bss
- All (no without) 35024 9940 336 4104
- without client 25684 7144 336 4104
- without client, exts 21652 6288 288 4104
- without client, exts, debug[1] 19756 3768 288 4104
- without server 30304 8160 336 4104
- without server, exts 25382 7204 288 4104
- without server, exts, debug[1] 23712 4256 288 4104
-[1] --disable-debug only removes messages below lwsl_notice. Since that is
-the default logging level the impact is not noticable, error, warn and notice
+| | .text | .rodata | .data | .bss |
+|--------------------------------|---------|---------|-------|------|
+| All (no without) | 35024 | 9940 | 336 | 4104 |
+| without client | 25684 | 7144 | 336 | 4104 |
+| without client, exts | 21652 | 6288 | 288 | 4104 |
+| without client, exts, debug[1] | 19756 | 3768 | 288 | 4104 |
+| without server | 30304 | 8160 | 336 | 4104 |
+| without server, exts | 25382 | 7204 | 288 | 4104 |
+| without server, exts, debug[1] | 23712 | 4256 | 288 | 4104 |
+
+[1] `--disable-debug` only removes messages below `lwsl_notice`. Since that is
+the default logging level the impact is not noticeable, error, warn and notice
logs are all still there.
-[2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora
+[2] `1024` fd per process is the default limit (set by ulimit) in at least Fedora
and Ubuntu. You can make significant savings tailoring this to actual expected
-peak fds, ie, at a limit of 20, context creation allocation reduces to 4432 +
-240 = 4672)
+peak fds, ie, at a limit of `20`, context creation allocation reduces to `4432 +
+240 = 4672`)
[3] known header content is freed after connection establishment
-
-
-
diff --git a/README.coding b/README.coding.md
similarity index 65%
rename from README.coding
rename to README.coding.md
index 333011c..a8a9f9d 100644
--- a/README.coding
+++ b/README.coding.md
@@ -1,7 +1,7 @@
Daemonization
-------------
-There's a helper api lws_daemonize built by default that does everything you
+There's a helper api `lws_daemonize` built by default that does everything you
need to daemonize well, including creating a lock file. If you're making
what's basically a daemon, just call this early in your init to fork to a
headless background process and exit the starting process.
@@ -22,19 +22,19 @@
If you want to restrict that allocation, or increase it, you can use ulimit or
similar to change the avaiable number of file descriptors, and when restarted
-libwebsockets will adapt accordingly.
+**libwebsockets** will adapt accordingly.
Libwebsockets is singlethreaded
-------------------------------
Directly performing websocket actions from other threads is not allowed.
-Aside from the internal data being inconsistent in forked() processes,
-the scope of a wsi (struct websocket) can end at any time during service
-with the socket closing and the wsi freed.
+Aside from the internal data being inconsistent in `forked()` processes,
+the scope of a `wsi` (`struct websocket`) can end at any time during service
+with the socket closing and the `wsi` freed.
Websocket write activities should only take place in the
-"LWS_CALLBACK_SERVER_WRITEABLE" callback as described below.
+`LWS_CALLBACK_SERVER_WRITEABLE` callback as described below.
Only live connections appear in the user callbacks, so this removes any
possibility of trying to used closed and freed wsis.
@@ -49,14 +49,14 @@
------------------------------------
You should only send data on a websocket connection from the user callback
-"LWS_CALLBACK_SERVER_WRITEABLE" (or "LWS_CALLBACK_CLIENT_WRITEABLE" for
+`LWS_CALLBACK_SERVER_WRITEABLE` (or `LWS_CALLBACK_CLIENT_WRITEABLE` for
clients).
If you want to send something, do not just send it but request a callback
when the socket is writeable using
- - libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or
- - libwebsocket_callback_on_writable_all_protocol(protocol) for all connections
+ - `libwebsocket_callback_on_writable(context, wsi)`` for a specific `wsi`, or
+ - `libwebsocket_callback_on_writable_all_protocol(protocol)` for all connections
using that protocol to get a callback when next writeable.
Usually you will get called back immediately next time around the service
@@ -70,30 +70,30 @@
Do not rely on only your own WRITEABLE requests appearing
---------------------------------------------------------
-Libwebsockets may generate additional LWS_CALLBACK_CLIENT_WRITEABLE events
+Libwebsockets may generate additional `LWS_CALLBACK_CLIENT_WRITEABLE` events
if it met network conditions where it had to buffer your send data internally.
-So your code for LWS_CALLBACK_CLIENT_WRITEABLE needs to own the decision
+So your code for `LWS_CALLBACK_CLIENT_WRITEABLE` needs to own the decision
about what to send, it can't assume that just because the writeable callback
came it really is time to send something.
It's quite possible you get an 'extra' writeable callback at any time and
-just need to return 0 and wait for the expected callback later.
+just need to `return 0` and wait for the expected callback later.
Closing connections from the user side
--------------------------------------
-When you want to close a connection, you do it by returning -1 from a
+When you want to close a connection, you do it by returning `-1` from a
callback for that connection.
-You can provoke a callback by calling libwebsocket_callback_on_writable on
+You can provoke a callback by calling `libwebsocket_callback_on_writable` on
the wsi, then notice in the callback you want to close it and just return -1.
But usually, the decision to close is made in a callback already and returning
-1 is simple.
If the socket knows the connection is dead, because the peer closed or there
-was an affirmitive network error like a FIN coming, then libwebsockets will
+was an affirmitive network error like a FIN coming, then **libwebsockets** will
take care of closing the connection automatically.
If you have a silently dead connection, it's possible to enter a state where
@@ -106,10 +106,11 @@
-------------------
To support fragmented messages you need to check for the final
-frame of a message with libwebsocket_is_final_fragment. This
-check can be combined with libwebsockets_remaining_packet_payload
+frame of a message with `libwebsocket_is_final_fragment`. This
+check can be combined with `libwebsockets_remaining_packet_payload`
to gather the whole contents of a message, eg:
+```
case LWS_CALLBACK_RECEIVE:
{
Client * const client = (Client *)user;
@@ -128,29 +129,30 @@
client->AppendMessageFragment(in, len, remaining);
}
break;
+```
-The test app llibwebsockets-test-fraggle sources also show how to
+The test app libwebsockets-test-fraggle sources also show how to
deal with fragmented messages.
Debug Logging
-------------
-Also using lws_set_log_level api you may provide a custom callback to actually
+Also using `lws_set_log_level` api you may provide a custom callback to actually
emit the log string. By default, this points to an internal emit function
-that sends to stderr. Setting it to NULL leaves it as it is instead.
+that sends to stderr. Setting it to `NULL` leaves it as it is instead.
-A helper function lwsl_emit_syslog() is exported from the library to simplify
-logging to syslog. You still need to use setlogmask, openlog and closelog
+A helper function `lwsl_emit_syslog()` is exported from the library to simplify
+logging to syslog. You still need to use `setlogmask`, `openlog` and `closelog`
in your user code.
The logging apis are made available for user code.
-lwsl_err(...)
-lwsl_warn(...)
-lwsl_notice(...)
-lwsl_info(...)
-lwsl_debug(...)
+- `lwsl_err(...)`
+- `lwsl_warn(...)`
+- `lwsl_notice(...)`
+- `lwsl_info(...)`
+- `lwsl_debug(...)`
The difference between notice and info is that notice will be logged by default
whereas info is ignored by default.
@@ -159,22 +161,22 @@
External Polling Loop support
-----------------------------
-libwebsockets maintains an internal poll() array for all of its
+**libwebsockets** maintains an internal `poll()` array for all of its
sockets, but you can instead integrate the sockets into an
-external polling array. That's needed if libwebsockets will
+external polling array. That's needed if **libwebsockets** will
cooperate with an existing poll array maintained by another
server.
-Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
-LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
+Four callbacks `LWS_CALLBACK_ADD_POLL_FD`, `LWS_CALLBACK_DEL_POLL_FD`,
+`LWS_CALLBACK_SET_MODE_POLL_FD` and `LWS_CALLBACK_CLEAR_MODE_POLL_FD`
appear in the callback for protocol 0 and allow interface code to
manage socket descriptors in other poll loops.
-You can pass all pollfds that need service to libwebsocket_service_fd(), even
-if the socket or file does not belong to libwebsockets it is safe.
+You can pass all pollfds that need service to `libwebsocket_service_fd()`, even
+if the socket or file does not belong to **libwebsockets** it is safe.
-If libwebsocket handled it, it zeros the pollfd revents field before returning.
-So you can let libwebsockets try and if pollfd->revents is nonzero on return,
+If **libwebsocket** handled it, it zeros the pollfd `revents` field before returning.
+So you can let **libwebsockets** try and if `pollfd->revents` is nonzero on return,
you know it needs handling by your code.
@@ -184,13 +186,17 @@
The library is ready for use by C++ apps. You can get started quickly by
copying the test server
+```bash
$ cp test-server/test-server.c test.cpp
+```
and building it in C++ like this
+```bash
$ g++ -DINSTALL_DATADIR=\"/usr/share\" -ocpptest test.cpp -lwebsockets
+```
-INSTALL_DATADIR is only needed because the test server uses it as shipped, if
+`INSTALL_DATADIR` is only needed because the test server uses it as shipped, if
you remove the references to it in your app you don't need to define it on
the g++ line either.
@@ -198,11 +204,11 @@
Availability of header information
----------------------------------
-From v1.2 of the library onwards, the HTTP header content is free()d as soon
+From v1.2 of the library onwards, the HTTP header content is `free()`d as soon
as the websocket connection is established. For websocket servers, you can
-copy interesting headers by handling LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION
+copy interesting headers by handling `LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION`
callback, for clients there's a new callback just for this purpose
-LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH.
+`LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH`.
TCP Keepalive
@@ -214,7 +220,7 @@
incoming data or sign the link is dead until you try to send.
To deal with getting a notification of that situation, you can choose to
-enable TCP keepalives on all libwebsockets sockets, when you create the
+enable TCP keepalives on all **libwebsockets** sockets, when you create the
context.
To enable keepalive, set the ka_time member of the context creation parameter
@@ -223,45 +229,44 @@
With keepalive enabled, the TCP layer will send control packets that should
stimulate a response from the peer without affecting link traffic. If the
-response is not coming, the socket will announce an error at poll() forcing
+response is not coming, the socket will announce an error at `poll()` forcing
a close.
-Note that BSDs don't support keepalive time / probes / inteveral per-socket
+Note that BSDs don't support keepalive time / probes / interval per-socket
like Linux does. On those systems you can enable keepalive by a nonzero
-value in ka_time, but the systemwide kernel settings for the time / probes/
-interval are used, regardless of what nonzero value is in ka_time.
+value in `ka_time`, but the systemwide kernel settings for the time / probes/
+interval are used, regardless of what nonzero value is in `ka_time`.
Optimizing SSL connections
--------------------------
-There's a member ssl_cipher_list in the lws_context_creation_info struct
+There's a member `ssl_cipher_list` in the `lws_context_creation_info` struct
which allows the user code to restrict the possible cipher selection at
context-creation time.
-You might want to look into that to stop the ssl peers selecting a ciher which
+You might want to look into that to stop the ssl peers selecting a cipher which
is too computationally expensive. To use it, point it to a string like
-"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
+`"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"`
-if left NULL, then the "DEFAULT" set of ciphers are all possible to select.
+if left `NULL`, then the "DEFAULT" set of ciphers are all possible to select.
Async nature of client connections
----------------------------------
-When you call libwebsocket_client_connect(..) and get a wsi back, it does not
+When you call `libwebsocket_client_connect(..)` and get a `wsi` back, it does not
mean your connection is active. It just mean it started trying to connect.
Your client connection is actually active only when you receive
-LWS_CALLBACK_CLIENT_ESTABLISHED for it.
+`LWS_CALLBACK_CLIENT_ESTABLISHED` for it.
There's a 5 second timeout for the connection, and it may give up or die for
other reasons, if any of that happens you'll get a
-LWS_CALLBACK_CLIENT_CONNECTION_ERROR callback on protocol 0 instead for the
-wsi.
+`LWS_CALLBACK_CLIENT_CONNECTION_ERROR` callback on protocol 0 instead for the
+`wsi`.
-After attempting the connection and getting back a non-NULL wsi you should
-loop calling libwebsocket_service() until one of the above callbacks occurs.
+After attempting the connection and getting back a non-`NULL` `wsi` you should
+loop calling `libwebsocket_service()` until one of the above callbacks occurs.
-As usual, see test-client.c for example code.
-
+As usual, see [test-client.c](test-server/test-client.c) for example code.
diff --git a/README b/README.md
similarity index 80%
rename from README
rename to README.md
index ac17dc0..e84a07d 100644
--- a/README
+++ b/README.md
@@ -1,3 +1,11 @@
+[![Travis Build Status](https://travis-ci.org/warmcat/libwebsockets.png)](https://travis-ci.org/warmcat/libwebsockets)
+[![Appveyor Build status](https://ci.appveyor.com/api/projects/status/6aq2tpajh1nmy6b3)](https://ci.appveyor.com/project/warmcat/libwebsockets)
+[![Coverity Scan Build Status](https://scan.coverity.com/projects/2506/badge.svg)](https://scan.coverity.com/projects/2506)
+
+
+libwebsockets
+-------------
+
This is the libwebsockets C library for lightweight websocket clients and
servers. For support, visit
@@ -9,17 +17,18 @@
You can get the latest version of the library from git
-http://git.libwebsockets.org
-https://github.com/warmcat/libwebsockets
+- http://git.libwebsockets.org
+- https://github.com/warmcat/libwebsockets
for more information:
-README.build - information on building the library
-README.coding - information for writing code using the library
-README.test-apps - information about the test apps built with the library
+- [README.build.md](README.build.md) - information on building the library
+- [README.coding.md](README.coding.md) - information for writing code using the library
+- [README.test-apps.md](README.test-apps.md) - information about the test apps built with the library
-After 1.3, tags will be signed using a key corresponding to this public key
+After libwebsockets 1.3, tags will be signed using a key corresponding to this public key
+```
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1
@@ -72,3 +81,4 @@
+AWJGq/WfB7N6pPh8S/XMW4e6ptuUodjiA==
=HV8t
-----END PGP PUBLIC KEY BLOCK-----
+```
diff --git a/README.test-apps b/README.test-apps.md
similarity index 78%
rename from README.test-apps
rename to README.test-apps.md
index f8fb050..2a6635d 100644
--- a/README.test-apps
+++ b/README.test-apps.md
@@ -1,17 +1,17 @@
Testing server with a browser
-----------------------------
-If you run libwebsockets-test-server and point your browser
+If you run [libwebsockets-test-server](test-server/test-server.c) and point your browser
(eg, Chrome) to
http://127.0.0.1:7681
-It will fetch a script in the form of test.html, and then run the
+It will fetch a script in the form of `test.html`, and then run the
script in there on the browser to open a websocket connection.
Incrementing numbers should appear in the browser display.
By default the test server logs to both stderr and syslog, you can control
-what is logged using -d <log level>, see later.
+what is logged using `-d <log level>`, see later.
Running test server as a Daemon
@@ -19,21 +19,23 @@
You can use the -D option on the test server to have it fork into the
background and return immediately. In this daemonized mode all stderr is
-disabled and logging goes only to syslog, eg, /var/log/messages or similar.
+disabled and logging goes only to syslog, eg, `/var/log/messages` or similar.
-The server maintains a lockfile at /tmp/.lwsts-lock that contains the pid
+The server maintains a lockfile at `/tmp/.lwsts-lock` that contains the pid
of the master process, and deletes this file when the master process
terminates.
To stop the daemon, do
- kill `cat /tmp/.lwsts-lock`
+```bash
+$ kill `cat /tmp/.lwsts-lock`
+```
If it finds a stale lock (the pid mentioned in the file does not exist
any more) it will delete the lock and create a new one during startup.
If the lock is valid, the daemon will exit with a note on stderr that
-it was already running.s
+it was already running.
Using SSL on the server side
@@ -41,7 +43,9 @@
To test it using SSL/WSS, just run the test server with
+```bash
$ libwebsockets-test-server --ssl
+```
and use the URL
@@ -54,7 +58,7 @@
in first https and then websocket wss, acting exactly the
same.
-test-server.c is all that is needed to use libwebsockets for
+[test-server.c](test-server/test-server.c) is all that is needed to use libwebsockets for
serving both the script html over http and websockets.
@@ -64,7 +68,9 @@
If you run the test server as described above, you can also
connect to it using the test client as well as a browser.
+```bash
$ libwebsockets-test-client localhost
+```
will by default connect to the test server on localhost:7681
and print the dumb increment number from the server at the
@@ -76,22 +82,28 @@
Testing simple echo
-------------------
-You can test against echo.websockets.org as a sanity test like
-this (the client connects to port 80 by default):
+You can test against `echo.websockets.org` as a sanity test like
+this (the client connects to port `80` by default):
+```bash
$ libwebsockets-test-echo --client echo.websocket.org
+```
This echo test is of limited use though because it doesn't
negotiate any protocol. You can run the same test app as a
local server, by default on localhost:7681
+```bash
$ libwebsockets-test-echo
+```
and do the echo test against the local echo server
+```bash
$ libwebsockets-test-echo --client localhost --port 7681
+```
-If you add the --ssl switch to both the client and server, you can also test
+If you add the `--ssl` switch to both the client and server, you can also test
with an encrypted link.
@@ -100,11 +112,13 @@
To test SSL/WSS client action, just run the client test with
+```bash
$ libwebsockets-test-client localhost --ssl
+```
By default the client test applet is set to accept selfsigned
certificates used by the test server, this is indicated by the
-use_ssl var being set to 2. Set it to 1 to reject any server
+`use_ssl` var being set to `2`. Set it to `1` to reject any server
certificate that it doesn't have a trusted CA cert for.
@@ -115,7 +129,8 @@
websocket server using 04 protocol and pings it like the
normal unix ping utility.
-$ libwebsockets-test-ping localhost
+```bash
+$ libwebsockets-test-ping localhost
handshake OK for protocol lws-mirror-protocol
Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
64 bytes from localhost: req=1 time=0.1ms
@@ -131,20 +146,21 @@
8 packets transmitted, 8 received, 0% packet loss, time 7458ms
rtt min/avg/max = 0.110/0.185/0.218 ms
$
+```
By default it sends 64 byte payload packets using the 04
PING packet opcode type. You can change the payload size
-using the -s= flag, up to a maximum of 125 mandated by the
+using the `-s=` flag, up to a maximum of 125 mandated by the
04 standard.
Using the lws-mirror protocol that is provided by the test
server, libwebsockets-test-ping can also use larger payload
sizes up to 4096 is BINARY packets; lws-mirror will copy
them back to the client and they appear as a PONG. Use the
--m flag to select this operation.
+`-m` flag to select this operation.
The default interval between pings is 1s, you can use the -i=
-flag to set this, including fractions like -i=0.01 for 10ms
+flag to set this, including fractions like `-i=0.01` for 10ms
interval.
Before you can even use the PING opcode that is part of the
@@ -152,7 +168,7 @@
protocol. By default lws-mirror-protocol is used which is
supported by the test server. But if you are using it on
another server, you can specify the protcol to handshake with
-by --protocol=protocolname
+by `--protocol=protocolname`
Fraggle test app
@@ -160,6 +176,7 @@
By default it runs in server mode
+```bash
$ libwebsockets-test-fraggle
libwebsockets test fraggle
(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
@@ -172,11 +189,13 @@
Spamming 895 random fragments
Spamming session over, len = 875970. sum = 0x6A74DA1
...
+```
You need to run a second session in client mode, you have to
-give the -c switch and the server address at least:
+give the `-c` switch and the server address at least:
-$ libwebsockets-test-fraggle -c localhost
+```bash
+$ libwebsockets-test-fraggle -c localhost
libwebsockets test fraggle
(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
Client mode
@@ -189,6 +208,7 @@
EOM received 247140 correctly from 258 fragments
EOM received 695451 correctly from 692 fragments
...
+```
The fraggle test sends a random number up to 1024 fragmented websocket frames
each of a random size between 1 and 2001 bytes in a single message, then sends
@@ -203,13 +223,15 @@
-------------
The http_proxy environment variable is respected by the client
-connection code for both ws:// and wss://. It doesn't support
+connection code for both `ws://` and `wss://`. It doesn't support
authentication.
You use it like this
-export http_proxy=myproxy.com:3128
-libwebsockets-test-client someserver.com
+```bash
+$ export http_proxy=myproxy.com:3128
+$ libwebsockets-test-client someserver.com
+```
debug logging
@@ -217,27 +239,27 @@
By default logging of severity "notice", "warn" or "err" is enabled to stderr.
-Again by default other logging is comiled in but disabled from printing.
+Again by default other logging is compiled in but disabled from printing.
If you want to eliminate the debug logging below notice in severity, use the
---disable-debug configure option to have it removed from the code by the
+`--disable-debug` configure option to have it removed from the code by the
preprocesser.
If you want to see more detailed debug logs, you can control a bitfield to
-select which logs types may print using the lws_set_log_level() api, in the
-test apps you can use -d <number> to control this. The types of logging
+select which logs types may print using the `lws_set_log_level()` api, in the
+test apps you can use `-d <number>` to control this. The types of logging
available are (OR together the numbers to select multiple)
- 1 ERR
- 2 WARN
- 4 NOTICE
- 8 INFO
- 16 DEBUG
- 32 PARSER
- 64 HEADER
- 128 EXTENSION
- 256 CLIENT
- 512 LATENCY
+ - 1 ERR
+ - 2 WARN
+ - 4 NOTICE
+ - 8 INFO
+ - 16 DEBUG
+ - 32 PARSER
+ - 64 HEADER
+ - 128 EXTENSION
+ - 256 CLIENT
+ - 512 LATENCY
Websocket version supported
@@ -250,13 +272,13 @@
Latency Tracking
----------------
-Since libwebsockets runs using poll() and a single threaded approach, any
+Since libwebsockets runs using `poll()` and a single threaded approach, any
unexpected latency coming from system calls would be bad news. There's now
-a latency tracking scheme that can be built in with --with-latency at
+a latency tracking scheme that can be built in with `--with-latency` at
configure-time, logging the time taken for system calls to complete and if
the whole action did complete that time or was deferred.
-You can see the detailed data by enabling logging level 512 (eg, -d 519 on
+You can see the detailed data by enabling logging level 512 (eg, `-d 519` on
the test server to see that and the usual logs), however even without that
the "worst" latency is kept and reported to the logs with NOTICE severity
when the context is destroyed.
@@ -269,4 +291,3 @@
here may indicate a problem, or if you system is loaded with another app at
that time, such as the browser, it may simply indicate the OS gave preferential
treatment to the other app during that call.
-