API Documentation

This page documents the functions presented by the lua-httpd network extension library, along with some simple notes on how to load the library and start using it.

Using the Extension

Once the library has been installed upon the system it will be automatically available for use by all your Lua scripts.

This is the preferred way to load the library and gain access to all the functions contained within it:

-- Load the library from the system installation
socket = require( "libhttpd" );

If you choose not to install the library system-wide you may instead load it via something like this:

-- Load the library from the current directory.
socket = assert(loadlib("./libhttpd.so", "luaopen_libhttpd"))()

-- Test it worked.
print ( sockets.version .. " loaded OK" );

Network Primitives Overview

The networking extension implements and exports the following networking primitives:

bind()

Listen upon a port to accept incoming connections.

accept()

Accept a new client connection from a socket, which has previously been returned from a call to bind().

connect()

Make an outgoing TCP/IP connection to a remote host.

read()

Read data from a connected socket.

write()

Write data to a connected socket.

close()

Close an open socket.

Filesystem Primitives Overview

The extension library also implements three utility functions which are useful when working with local files.

is_dir()

Test whether a directory entry is a directory.

is_file()

Test whether a directory entry is a file.

readdir()

Read the name of each file in a given directory.

Detailed API Documentation

bind()

Usage:

listener = socket.bind( port );

This function returns a socket object which is listening upon the given port. It will return nil in the case of any error.

Once you have bound a socket you should use the accept() call to actually handle an incoming connection.

accept()

Usage:

incoming = socket.accept( listener );

This function accepts an incoming connection from a socket which has been returned from the bind() function. It will not return until a new client connects.

read()

Usage:

length, data = socket.read( incoming );

This function will read and return data from a connected socket. The returned values are the actual data and the length of that data.

write()

Usage:

socket.write( incoming, data [, length ] );

This function writes data to a connected socket. You must specify the socket to write to and the data - optionally you may specify the size of the data to write.

close()

Usage:

socket.close( listener );

This function closes an open socket - either one returned from accept(), or from connect().

is_dir( path )

Usage:

ret = socket.is_dir( "/etc/" );

This function will return true if the named directory entry is actually a directory.

is_file( path )

Usage:

ret = socket.is_file( "/etc/passwd" );

This function will return true if the named directory entry is actually a file.

readdir( path )

Usage:

files = socket.readdir( "/etc" );

This function will return a table containing the directory entries found beneath the given path. To manipulate the results you may use something like the following:

--  Read directory entries.
entries = socket.readdir( "/etc" );

-- For each entry
for i=0,table.getn(entries) do
   print( "Found " .. entries[i] );
end