Split docs by sections

README.md

@@ -30,7 +30,7 @@ simplicity by carefully selected list of features:
   [upload.c](https://github.com/cesanta/mongoose/blob/master/examples/upload.c),
   [websocket.c](https://github.com/cesanta/mongoose/blob/master/examples/websocket.c)
 - HTTP client capable of sending arbitrary HTTP/HTTPS requests
-- [User Manual](https://github.com/cesanta/mongoose/blob/master/docs/UserManual.md)
+- [User Manual](https://github.com/cesanta/mongoose/blob/master/docs/README.md)
 
 Note that Windows and MacOS binaries have following 3rd party software
 compiled in:

docs/API.md

+# Mongoose Server Embedding Guide And API Reference
+
+Embedding Mongoose is easy. Copy
+[mongoose.c](https://github.com/cesanta/mongoose/blob/master/mongoose.c) and
+[mongoose.h](https://github.com/cesanta/mongoose/blob/master/mongoose.h)
+to your application's source tree and include them in the build. For
+example, your application's code lives in C file `my_app.c`, then on UNIX
+this command embeds Mongoose:
+
+    $ ls
+    my_app.c mongoose.c mongoose.h
+    $ gcc my_app.c mongoose.c -o my_app -ldl -pthread
+
+Somewhere in the application code, call `mg_start()` to start the server.
+Pass configuration options and event handlers to `mg_start()`.
+Mongoose then calls handlers when certain events happen.
+For example, when new request arrives, Mongoose calls `begin_request`
+handler function to let user handle the request. In the handler, user code
+can get all information about the request -- parsed headers, etcetera.
+
+Mongoose API is logically divided in three categories: server setup/shutdown
+functions, functions to be used by user-written event handlers, and
+convenience utility functions.
+
+### Starting and stopping embedded web server
+To start the embedded web server, call `mg_start()`. To stop it, call
+`mg_stop()`.
+
+    // This structure needs to be passed to mg_start(), to let mongoose know
+    // which callbacks to invoke.
+    struct mg_callbacks {
+      int  (*begin_request)(struct mg_connection *);
+      void (*end_request)(const struct mg_connection *, int reply_status_code);
+      int  (*log_message)(const struct mg_connection *, const char *message);
+      int  (*init_ssl)(void *ssl_context);
+      int (*websocket_connect)(const struct mg_connection *);
+      void (*websocket_ready)(struct mg_connection *);
+      int  (*websocket_data)(struct mg_connection *);
+      const char * (*open_file)(const struct mg_connection *,
+                                 const char *path, size_t *data_len);
+      void (*init_lua)(struct mg_connection *, void *lua_context);
+      void (*upload)(struct mg_connection *, const char *file_name);
+      int  (*http_error)(struct mg_connection *, int status);
+    };
+
+[hello.c](https://github.com/cesanta/mongoose/blob/master/examples/hello.c)
+provides a minimalistic example.
+
+Common pattern is to implement `begin_request` callback, and serve static files
+from memory, and/or construct dynamic replies on the fly. Here is
+my [embed.c](https://gist.github.com/valenok/4714740) gist
+that shows how to easily any data can be embedded
+directly into the executable. If such data needs to be encrypted, then
+encrypted database or encryption dongles would be a better choice.
+
+

docs/AndroidBuild.md

+# Mongoose Server Build on Android
+
+This is a small guide to help you run mongoose on Android. Currently it is
+tested on the HTC Wildfire. If you have managed to run it on other devices
+as well, please comment or drop an email in the mailing list.
+Note : You dont need root access to run mongoose on Android.
+
+- Download the source from the Downloads page.
+- Download the Android NDK from [http://developer.android.com/tools/sdk/ndk/index.html](http://developer.android.com/tools/sdk/ndk/index.html)
+- Run `/path-to-ndk/ndk-build -C /path-to-mongoose/build`
+  That should generate mongoose/lib/armeabi/mongoose
+- Using the adb tool (you need to have Android SDK installed for that),
+  push the generated mongoose binary to `/data/local` folder on device.
+- From adb shell, navigate to `/data/local` and execute `./mongoose`.
+- To test if the server is running fine, visit your web-browser and
+  navigate to `http://127.0.0.1:8080` You should see the `Index of /` page.
+
+![screenshot](https://a248.e.akamai.net/camo.github.com/b88428bf009a2b6141000937ab684e04cc8586af/687474703a2f2f692e696d6775722e636f6d2f62676f6b702e706e67)
+
+
+Notes:
+
+- `jni` stands for Java Native Interface. Read up on Android NDK if you want
+  to know how to interact with the native C functions of mongoose in Android
+  Java applications.
+- TODO: A Java application that interacts with the native binary or a
+  shared library.

docs/FAQ.md

+# Mongoose Web Server Common Problems
+
+- PHP doesn't work - getting empty page, or 'File not found' error. The
+  reason for that is wrong paths to the interpreter. Remember that with PHP,
+  correct interpreter is `php-cgi.exe` (`php-cgi` on UNIX). Solution: specify
+  full path to the PHP interpreter, e.g.:
+    `mongoose -cgi_interpreter /full/path/to/php-cgi`
+
+- Mongoose fails to start. If Mongoose exits immediately when run, this
+  usually indicates a syntax error in the configuration file
+  (named `mongoose.conf` by default) or the command-line arguments.
+  Syntax checking is omitted from Mongoose to keep its size low. However,
+  the Manual should be of help. Note: the syntax changes from time to time,
+  so updating the config file might be necessary after executable update.
+
+- Embedding with OpenSSL on Windows might fail because of calling convention.
+  To force Mongoose to use `__stdcall` convention, add `/Gz` compilation
+  flag in Visual Studio compiler.
+
+

docs/Internals.md

+# Mongoose Web Server Internals
+
+Mongoose is multithreaded web server. `mg_start()` function allocates
+web server context (`struct mg_context`), which holds all information
+about web server instance:
+
+- configuration options. Note that mongoose makes internal copies of
+  passed options.
+- SSL context, if any
+- user-defined callbacks
+- opened listening sockets
+- a queue for accepted sockets
+- mutexes and condition variables for inter-thread synchronization
+
+When `mg_start()` returns, all initialization is quaranteed to be complete
+(e.g. listening ports are opened, SSL is initialized, etc). `mg_start()` starts
+two threads: a master thread, that accepts new connections, and several
+worker threads, that process accepted connections. The number of worker threads
+is configurable via `num_threads` configuration option. That number puts a
+limit on number of simultaneous requests that can be handled by mongoose.
+
+When master thread accepts new connection, a new accepted socket (described by
+`struct socket`) it placed into the accepted sockets queue,
+which has size of 20 (see [code](https://github.com/cesanta/mongoose/blob/3892e0199e6ca9613b160535d9d107ede09daa43/mongoose.c#L486)). Any idle worker thread
+can grab accepted sockets from that queue. If all worker threads are busy,
+master thread can accept and queue up to 20 more TCP connections,
+filling up the queue.
+In the attempt to queue next accepted connection, master thread blocks
+until there is space in a queue. When master thread is blocked on a
+full queue, TCP layer in OS can also queue incoming connection.
+The number is limited by the `listen()` call parameter on listening socket,
+which is `SOMAXCONN` in case of Mongoose, and depends on a platform.
+
+Worker threads are running in an infinite loop, which in simplified form
+looks something like this:
+
+    static void *worker_thread() {
+      while (consume_socket()) {
+        process_new_connection();
+      }
+    }
+
+Function `consume_socket()` gets new accepted socket from the mongoose socket
+queue, atomically removing it from the queue. If the queue is empty,
+`consume_socket()` blocks and waits until new sockets are placed in a queue
+by the master thread. `process_new_connection()` actually processes the
+connection, i.e. reads the request, parses it, and performs appropriate action
+depending on a parsed request.
+
+Master thread uses `poll()` and `accept()` to accept new connections on
+listening sockets. `poll()` is used to avoid `FD_SETSIZE` limitation of
+`select()`. Since there are only a few listening sockets, there is no reason
+to use hi-performance alternatives like `epoll()` or `kqueue()`. Worker
+threads use blocking IO on accepted sockets for reading and writing data.
+All accepted sockets have `SO_RCVTIMEO` and `SO_SNDTIMEO` socket options set
+(controlled by `request_timeout_ms` mongoose option, 30 seconds default) which
+specify read/write timeout on client connection.
+
+

docs/LuaSqlite.md

+# Mongoose Web Server: Lua Server Pages
+
+Pre-built Windows and Mac mongoose binaries have built-in Lua Server Pages
+support. That means it is possible to write PHP-like scripts with mongoose,
+using Lua programming language instead of PHP. Lua is known
+for it's speed and small size. Mongoose uses Lua version 5.2.1, the
+documentation for it can be found at
+[Lua 5.2 reference manual](http://www.lua.org/manual/5.2/).
+
+To create a Lua Page, make sure a file has `.lp` extension. For example,
+let's say it is going to be `my_page.lp`. The contents of the file, just like
+with PHP, is HTML with embedded Lua code. Lua code must be enclosed in
+`<?  ?>` blocks, and can appear anywhere on the page. For example, to
+print current weekday name, one can write:
+
+    <p>
+      <span>Today is:</span>
+      <? mg.write(os.date("%A")) ?>
+    </p>
+
+Note that this example uses function `mg.write()`, which prints data to the
+web page. Using function `mg.write()` is the way to generate web content from
+inside Lua code. In addition to `mg.write()`, all standard library functions
+are accessible from the Lua code (please check reference manual for details),
+and also information about the request is available in `mg.request_info` object,
+like request method, all headers, etcetera. Please refer to
+`struct mg_request_info` definition in
+[mongoose.h](https://github.com/cesanta/mongoose/blob/master/mongoose.h)
+to see what kind of information is present in `mg.request_info` object. Also,
+[page.lp](https://github.com/cesanta/mongoose/blob/master/test/page.lp) and
+[prime_numbers.lp](https://github.com/cesanta/mongoose/blob/master/examples/lua/prime_numbers.lp)
+contains some example code that uses `request_info` and other functions(form submitting for example).
+
+Mongoose exports the following to the Lua server page:
+
+    mg.read()         -- reads a chunk from POST data, returns it as a string
+    mg.write(str)     -- writes string to the client
+    mg.include(path)  -- sources another Lua file
+    mg.redirect(uri)  -- internal redirect to a given URI
+    mg.onerror(msg)   -- error handler, can be overridden
+    mg.version        -- a string that holds Mongoose version
+    mg.request_info   -- a table with request information
+
+    -- Connect to the remote TCP server. This function is an implementation
+    -- of simple socket interface. It returns a socket object with three
+    -- methods: send, recv, close, which are synchronous (blocking).
+    -- connect() throws an exception on connection error.
+    connect(host, port, use_ssl)
+
+    -- Example of using connect() interface:
+    local host = 'code.google.com'  -- IP address or domain name
+    local ok, sock = pcall(connect, host, 80, 1)
+    if ok then
+      sock:send('GET /p/mongoose/ HTTP/1.0\r\n' ..
+                'Host: ' .. host .. '\r\n\r\n')
+      local reply = sock:recv()
+      sock:close()
+      -- reply now contains the web page https://code.google.com/p/mongoose
+    end
+
+
+**IMPORTANT: Mongoose does not send HTTP headers for Lua pages. Therefore,
+every Lua Page must begin with HTTP reply line and headers**, like this:
+
+    <? print('HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n') ?>
+    <html><body>
+      ... the rest of the web page ...
+
+To serve Lua Page, mongoose creates Lua context. That context is used for
+all Lua blocks within the page. That means, all Lua blocks on the same page
+share the same context. If one block defines a variable, for example, that
+variable is visible in the block that follows.
+
+

docs/README.md

+   * [Usage Guide](Usage.md)
+   * [Configuration Options](Options.md)
+   * [Embedding Guide and API reference](API.md)
+   * [Lua and Sqlite Support](LuaSqlite.md)
+   * [Android Build](AndroidBuild.md)
+   * [Common Problems](FAQ.md)
+   * [Mongoose Internal Architecture](Internals.md)
+
+Other resources on Mongoose:
+
+- Presentation made by Arnout Vandecappelle at FOSDEM 2011 on 2011-02-06
+  in Brussels, Belgium, called
+  "Creating secure web based user interfaces for Embedded Devices"
+  ([pdf](http://mind.be/content/110206_Web-ui.pdf) |
+   [odp](http://mind.be/content/110206_Web-ui.odp))
+- Linux Journal article by Michel J.Hammel, 2010-04-01, called
+  [Mongoose: an Embeddable Web Server in C](http://www.linuxjournal.com/article/10680)

docs/Usage.md

+# Mongoose Web Server usage guide
+
+Mongoose is small and easy to use web server. It is self-contained, and does
+not require any external software to run.
+
+On Windows, mongoose iconifies itself to the system tray icon when started.
+Right-click on the icon pops up a menu, where it is possible to stop
+mongoose, or configure it, or install it as Windows service. The easiest way
+to share a folder on Windows is to copy `mongoose.exe` to a folder,
+double-click the exe, and launch a browser at
+[http://localhost:8080](http://localhost:8080). Note that 'localhost' should
+be changed to a machine's name if a folder is accessed from other computer.
+
+On UNIX and Mac, mongoose is a command line utility. Running `mongoose` in
+terminal, optionally followed by configuration parameters
+(`mongoose [OPTIONS]`) or configuration file name
+(`mongoose [config_file_name]`) starts the
+web server. Mongoose does not detach from terminal. Pressing `Ctrl-C` keys
+would stop the server.
+
+When started, mongoose first searches for the configuration file.
+If configuration file is specified explicitly in the command line, i.e.
+`mongoose path_to_config_file`, then specified configuration file is used.
+Otherwise, mongoose would search for file `mongoose.conf` in the same directory
+where binary is located, and use it. Configuration file can be absent.
+
+
+Configuration file is a sequence of lines, each line containing
+command line argument name and it's value. Empty lines, and lines beginning
+with `#`, are ignored. Here is the example of `mongoose.conf` file:
+
+    document_root c:\www
+    listening_ports 8080,8043s
+    ssl_certificate c:\mongoose\ssl_cert.pem
+
+When configuration file is processed, mongoose process command line arguments,
+if they are specified. Command line arguments therefore can override
+configuration file settings. Command line arguments must start with `-`.
+For example, if `mongoose.conf` has line
+`document_root /var/www`, and mongoose has been started as
+`mongoose -document_root /etc`, then `/etc` directory will be served as
+document root, because command line options take priority over
+configuration file. Configuration options section below provide a good
+overview of Mongoose features.
+
+Note that configuration options on the command line must start with `-`,
+but their names are the same as in the config file. All option names are
+listed in the next section. Thus, the following two setups are equivalent:
+
+    # Using command line arguments
+    $ mongoose -listening_ports 1234 -document_root /var/www
+
+    # Using config file
+    $ cat mongoose.conf
+    listening_ports 1234
+    document_root /var/www
+    $ mongoose
+
+Mongoose can also be used to modify `.htpasswd` passwords file:
+
+    mongoose -A <htpasswd_file> <realm> <user> <passwd>
+
+Unlike other web servers, mongoose does not require CGI scripts be located in
+a special directory. CGI scripts can be anywhere. CGI (and SSI) files are
+recognized by the file name pattern. Mongoose uses shell-like glob
+patterns. Pattern match starts at the beginning of the string, so essentially
+patterns are prefix patterns. Syntax is as follows:
+
+     **      Matches everything
+     *       Matches everything but slash character, '/'
+     ?       Matches any character
+     $       Matches the end of the string
+     |       Matches if pattern on the left side or the right side matches.
+
+All other characters in the pattern match themselves. Examples:
+
+    **.cgi$      Any string that ends with .cgi
+    /foo         Any string that begins with /foo
+    **a$|**b$    Any string that ends with a or b
+
+