Docs added

docs/API.md

+# Mongoose Embedding Guide
+
+Embedding Mongoose is done in two steps:
+
+   1. Copy
+    [mongoose.c](https://raw.github.com/cesanta/mongoose/master/mongoose.c) and
+    [mongoose.h](https://raw.github.com/cesanta/mongoose/master/mongoose.h)
+    to your application's source tree and include these two files in the build.
+   2. Somewhere in the application code, call `mg_start()` to start the server.
+    Pass configuration options and event handlers to `mg_start()`. Call
+    `mg_stop()` when server needs to be stopped.
+
+Mongoose calls event handlers when certain events happen.
+For example, when new request arrives, Mongoose calls `begin_request`
+handler to let user handle the request. In the handler, user code
+can get all information about the request -- parsed headers, etcetera.
+Here is a list of well-commented embedding examples:
+
+   * [hello.c](https://github.com/cesanta/mongoose/blob/master/examples/hello.c)
+    This is the most basic "Hello, world!" example
+   * [post.c](https://github.com/cesanta/mongoose/blob/master/examples/post.c)
+    This example shows how to handle form submission
+   * [upload.c](https://github.com/cesanta/mongoose/blob/master/examples/upload.c)
+    This example shows how to handle file upload
+   * [websocket.c](https://github.com/cesanta/mongoose/blob/master/examples/websocket.c)
+    This example shows how to handle websocket requests
+   * [chat.c](https://github.com/cesanta/mongoose/blob/master/examples/chat.c), [main.js](https://github.com/cesanta/mongoose/blob/master/examples/html/main.js)
+    An example of web chat application, with cookie-based user authentication,
+    session support. All UI is done using static HTML/CSS. Interaction
+    with backed is done using AJAX.
+
+
+
+# API Reference
+
+## mg\_start()
+    struct mg_context *mg_start(const char **configuration_options
+                                int (*event_handler_func)(struct mg_event *),
+                                void *user_data);
+
+Starts mongoose web server. This function starts a separate master thread,
+which opens listening sockets, and `num_threads` worker threads, which are
+used to handle incoming requests.
+
+  `options`: NULL terminated list of option_name, option_value pairs that
+            specify Mongoose configuration parameters.  
+  `event_handler`: a function that will be called on specific events,
+               see description below.  
+  `user_data`: Opaque pointer, used by application developer to store
+               global private data.  
+  Return: web server context, or NULL on error.
+
+  Side-effects: on UNIX, `mg_start()` ignores `SIGPIPE` signals. If custom
+    processing is required `SIGPIPE`, signal handler must be set up
+    after calling `mg_start()`.
+
+ Important: Mongoose does not install `SIGCHLD` handler. If CGI is used,
+ `SIGCHLD` handler must be set up to reap CGI zombie processes.
+
+
+## mg\_stop()
+
+    void mg_stop(struct mg_context *);
+
+Stop the web server. This function blocks until all Mongoose
+threads are stopped. Context pointer becomes invalid.
+
+
+## Events triggered by Mongoose
+
+Every time an event happens, such as new connection being made,
+Mongoose calls user-specified event handler. Mongoose passes `struct mg_event`
+structure to the event handler, which event handler can use to find any
+information required to handle an event:
+
+    struct mg_event {
+      int type;               // Event type
+      void *user_data;        // User data pointer passed to mg_start()
+      void *conn_data;        // Connection-specific, per-thread user data.
+      void *event_param;      // Event-specific parameter
+      struct mg_connection *conn;
+      struct mg_request_info *request_info;
+    };
+
+Below is a list of all events triggered by Mongoose:
+
+### MG\_REQUEST\_BEGIN
+
+Called when Mongoose has received and successfully parsed new HTTP request.
+`request_info`
+attribute of `struct mg_event` contains parsed HTTP request. Return value tells
+mongoose what to do next. If event handler returns 0, that means that the
+handler did not process the request, did not send any data to the client, and
+expects Mongoose to continue processing the request. Returning non-zero
+tells Mongoose to stop doing any processing, cause callback already sent
+valid reply to the client.
+
+### MG\_REQUEST\_END
+
+Called when mongoose has finished processing the request.
+Could be used to implement custom request logging, request execution time
+profiling, etcetera. Return value is ignored by Mongoose.
+
+### MG\_HTTP\_ERROR
+
+Called when Mongoose is about to send HTTP error to the client.
+`event_param` attribute contains integer HTTP error code, that could be
+accessed like this:  
+`int status_code = (int) (long) event->event_param;`  
+If handler returns zero, then Mongoose proceeds with sending error to the
+client, otherwise Mongoose will not send anything.
+
+### MG\_EVENT\_LOG
+
+Called when Mongoose wants to log an error message.
+Normally, error messages are logged to the error log file. If handler
+returns 0, mongoose will not log to the log file. `event_param` holds
+a message to be logged:  
+`const char *message = (const char *) event->event_param;`
+
+### MG\_THREAD\_BEGIN
+
+Called when Mongoose starts a new thread. Handler will be executing
+in the context of that new thread. It is used to perform any extra per-thread
+initialization. Return value is ignored by Mongoose.
+
+### MG\_THREAD\_END
+
+Called when Mongoose is about to terminate a thread. Used to clean up
+the state initialized by `MG_THREAD_BEGIN` handling. Return value is ignored.
+
+
+## Embedding Examples
+
+The common pattern is to handle `MG_REQUEST_BEGIN` 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 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.
+
+- Clone Mongoose Git repo
+- 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 FAQ
+
+### 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 to the Visual Studio project settings.

docs/Internals.md

+# Mongoose 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 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/SSL.md

+# Mongoose SSL guide
+
+SSL is a protocol that makes web communication secure. To enable SSL
+in mongoose, 3 steps are required:
+
+   1. Valid certificate file must be created
+   2. `ssl_certificate` options must be set to contain path to the
+       certificate file.
+   3. `listening_ports` option must contain a port number with letter `s`
+        appended to it, which instructs Mongoose to use SSL for all connections
+        made to that port.
+
+Below is the `mongoose.conf` file snippet for typical SSL setup:
+
+    document_root     www_root        # Serve files in www_root directory
+    listening_ports   80r,443s        # Redirect all HTTP requests to HTTPS
+    ssl_certificate   ssl_cert.pem    # Location of certificate file
+
+## How to create SSL certificate file
+
+SSL certificate file is a text file that must contain at least two
+sections:
+
+   1. A private key
+   2. A certificate
+
+Both sections should be chunks of text in PEM format. When PEM file is
+opened in a text editor, it looks like this:
+
+    -----BEGIN RSA PRIVATE KEY-----
+    MIIEogIBAAKCAQEAwONaLOP7EdegqjRuQKSDXzvHmFMZfBufjhELhNjo5KsL4ieH
+    hYN0Zii2yTb63jGxKY6gH1R/r9dL8kXaJmcZrfSa3AgywnteJWg=
+    -----END RSA PRIVATE KEY-----
+    -----BEGIN CERTIFICATE-----
+    MIIDBjCCAe4CCQCX05m0b053QzANBgkqhkiG9w0BAQQFADBFMQswCQYDVQQGEwJB
+    SEGI4JSxV56lYg==
+    -----END CERTIFICATE-----
+
+Two aforementioned sections are clearly seen. Typically, those section
+are bigger then in the example shown. The text between the `BEGIN` and
+`END` is the text representation of binary data, a private key and a
+certificate. Therefore, in order to create a certificate file,
+
+   * private key must be converted to PEM format
+   * certificate must be converted to PEM format
+   * those two should be concatenated into a single file
+
+If the certificate chain in used, a chain file also needs to be
+converted into PEM format and appended to the certificate file.
+
+## How SSL works
+
+SSL is a protocol that can encrypt communication between two parties. If third
+party observes all messages passed by, it would be very
+hard for the third party (though not impossible) to decrypt the communication.
+
+The idea is based on so-called public key encryption. Communicating parties
+have two keys: a public key and a private key. A public key is advertised
+to everybody, and it is contained in a certificate. A private key is kept
+secret. Security algorithm works in a way that anybody can encrypt
+a message using public key, and only private key can decrypt it.
+
+This is why web server needs both private key and certificate: private key
+is used to decrypt incoming messages, and certificate is used to tell the
+public key to the other party. When communication starts, parties exchange
+their public keys, and keep private keys to themselves. Man-in-the-middle
+who observes the communication is unable to decrypt the messages cause
+private keys are required for decryption.
+
+Encryption algorithms are built on top of hard mathematical problem, which
+makes it very expensive for man-in-the-middle to compute private keys.
+For example, RSA algorithm is based on a mathematical problem of factorization.
+It is easy to generate two very large prime numbers `P` and `Q` and make
+a product `P * Q`. But given a product, it is very hard to recover these
+two prime numbers - this is called factorization.

docs/Usage.md

+# Mongoose 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
+
+