README

lsocket

   A library that provides network programming support for Lua.

   Author: Gunnar Zötl , 2013-2014.
   Released under MIT/X11 license. See file LICENSE for details.

Introduction

   lsocket provides not complete, but good enough support for socket
   programming. It supports IPv4, IPv6 and unix domain sockets, and
   selects automatically which one to use based on the address you bind or
   connect to. Also, it is almost-nonblocking: except for lsocket.select()
   and nameserver lookups, nothing ever blocks ([1]*). And you can also
   make lsocket.select() nonblocking by passing 0 as a timeout value.
   lsocket has been tested with lua 5.1.5, 5.2.3 and luajit 2.0.1 on Linux
   and Mac OS X.

Installing

   This uses only stuff that comes with your system. Normally, calling
   sudo luarocks install lsocket

   or when you have an unpacked source folder,
   sudo luarocks make

   should do the right thing.

   There is also a Makefile in the distribution directory, which has been
   created for and on Linux and Mac OS X. This does not cater for
   installation, so the luarocks method is preferrable where possible.

Using

   lsocket = require "lsocket"

  Constructors

   socket = lsocket.bind( [type], [address], [port], [backlog] )
          creates a new socket and binds it locally.

    Arguments

        type
                (optional) type of socket to create, may be "udp", "tcp",
                or "mcast", defaults to "tcp". If the type is mcast, the
                socket will be a udp socket that is additionally set up
                for use as a ipv4 broadcast or ipv6 multicast client
                socket. mcast is not available for unix domain sockets.

        address
                (optional) ip address or hostname to bind to, defaults to
                lsocket.INADDR_ANY ('0.0.0.0'). If this is an IPv4
                address, the socket will be an IP socket, if it is an IPv6
                address, the socket will be an IPv6 socket, and if it
                contains a slash (/) character, it will be a unix domain
                socket with the address as the path on the file system. On
                linux, if the first char is '@', then it will be a unix
                domain socket with an abstract socket name, i.e. one that
                does not exist in the file system.

        port
                port number to bind to, meaningless with unix domain
                sockets.

        backlog
                (optional) length of connection backlog on this socket,
                defaults to 5. This is only useful for tcp sockets.

    Returns

          the bound socket, or nil+error message on error.

   socket = lsocket.connect( [type], address, port, [ttl] )
          connects to a remote socket.

    Arguments

        type
                (optional) type of socket to create, may be "udp", "tcp",
                or "mcast", defaults to "tcp". If the type is mcast, the
                socket will be a udp socket that is additionally set up
                for use as a ipv4 broadcast or ipv6 multicast server
                socket. mcast is not available for unix domain sockets.

        address
                ip address or hostname to connect to. See the address
                parameter to bind() above for a more detailed explanation.

        port
                port number to connect to, meaningless with unix domain
                sockets.

        ttl
                (optional) ttl for multicast packets, defaults to 1. Only
                useful if type is "mcast".

    Returns

          the socket in connecting state, or nil+error message on error.
          Note that you need to select() the socket for writing to wait
          for the connect to finish. Of course you can also select the
          socket for reading, but if you select for writing, select() will
          return as soon as the socket is connected, whereas if you select
          for reading, select() will return when the socket is connected
          and the server has sent data. In any case select() will return
          if the connection fails. You should call status() on a socket
          that was created by connect() after it is first returned from
          select() in order to see whether the connection was successful.

  Socket Methods

   tbl = socket:info( [what] )
          returns a table with information about the socket.

    Arguments

        what
                (optional) specify what info you are interested in. The
                result is returned in a table.

    Returns

          a table with the requested information:

          + If what is omitted or nil, return a standard set of socket
            infos.
            These fields are in the table:

              fd
                      socket file descriptor

              family
                      ip protocol family, "inet" or "inet6"

              type
                      "udp" or "tcp"

              listening
                      true if the socket is listening (created by
                      lsocket.bind), false otherwise

              multicast
                      true if the socket is a multicast socket, false
                      otherwise.

          + If what is "peer", return information about the socket peer.
            These fields are in the table:

              family
                      ip protocol family, "inet" or "inet6"

              addr
                      ip address

              port
                      port number

            If called on unix domain sockets, this will only return useful
            information for sockets created with lsocket.bind().
          + If what is "socket", return information about the local
            socket. Fields as for "peer". If called on unix domain
            sockets, this will only return useful information for sockets
            created with lsocket.connect().

   ok, err = socket:status()
          check a sockets error status.

    Returns

          true if the socket has no errors, nil + error message otherwise.

   fd = socket:getfd()
          returns a socket file descriptor. You probably don't need this,
          it is only for interaction with other packages.

    Returns

          the sockets file descriptor.

   ok, err = socket.setfd(newfd)
          sets a sockets file descriptor. Only -1 (incalid descriptor) is
          allowed as argument. You probably don't need this, it is only
          for interaction with other packages.

    Returns

          true if the descriptor was -1 and the sockets descriptor has
          been set to -1, nil + error message otherwise.

   sock, addr, port = socket:accept()
          accept a new connection on a socket

    Returns

          a new socket with the accepted connection and ip address and
          port of the remote end on success, false if no connection is
          available to accept, or nil+error message on error. If called
          with a unix domain socket, addr and port will be nil on success.

          This only works on tcp type sockets.

   string = socket:recv( [size] )
          reads data from a socket

    Arguments

        size
                (optional) the length of the buffer to use for reading,
                defaults to some internal value

    Returns

          a string containing the data read, false if no data was
          available to read, nil if the remote end closed the connection
          (tcp connections only), or nil+error message on error.

          This should only be used for tcp type sockets, or for udp type
          sockets that have been created by lsocket.connect(). For udp
          type sockets, that have been created with lsocket.bind(), see
          socket:recvfrom()

   string, address, port = socket:recvfrom( [size] )
          reads data from a socket

    Arguments

        size
                (optional) the length of the buffer to use for reading,
                defaults to 4096

    Returns

          a string containing the data read, and the ip address and port
          number of the remote end of the connection, false if no data was
          available to read, or nil+error message on error.

          This should only be used for udp type sockets. For tcp type
          sockets, see socket:recv()

   nbytes = socket:send(string)
          writes data to a socket

    Arguments

        string
                data to write to the socket

    Returns

          the number of bytes written, or false if the socket was not
          ready to accept data, or nil+error message on error.

          This should only be used for tcp type sockets, or for udp type
          sockets that have been created by lsocket.connect(). For udp
          type sockets, that have been created with lsocket.bind(), see
          socket:sendto()

   nbytes = socket:sendto(string, address, port)
          writes data to a socket

    Arguments

        string
                data to write to the socket

        address
                ip address of remote end of socket to send data to

        port
                port number of remote end of socket to send data to

    Returns

          the number of bytes written, or false if the socket was not
          ready to accept data, or nil+error message on error.

          This should only be used for udp type sockets. For tcp type
          sockets, see socket:send()

   ok = socket:close()
          closes a socket

    Returns

          true if closing the socket went ok, or nil+error message on
          error.

  Functions

   [read [, write]] = lsocket.select([read [, write]] , [timeout] )
          calls select() on up to 2 tables of sockets, has timeout

    Arguments

        read
                (opt) table of sockets to wait on for reading

        write
                (opt) table of sockets to wait on for writing

        timeout
                (opt) timeout in seconds (millisecond resolution),
                defaults to infinite.

          Either only the read socket table or values for both socket
          tables must be given. That means, if you want to wait on sockets
          for writing, you will also have to pass a table or nil for
          reading. The timeout value can be specified without passing any
          tables before it, so that lsocket.select(timeout) can be used as
          a millisecond precision sleep function. Closed sockets are
          ignored by lsocket.select(), and it is an error to call
          lsocket.select() without any open sockets and timeout.

    Returns

          either as many tables as were passed as arguments, each one
          filled with the sockets that became ready from the select, false
          if a timeout occurred before any socket became ready, or
          nil+error message on error.

          Note: if you pass nil for the read sockets and some table for
          the write sockets, when a socket you wait on becomes ready, an
          empty table is returned as first return value.

   tbl = lsocket.resolve(name)
          attempts a name resolution of its argument.

    Arguments

        name
                hostname to find ip address(es) for

    Returns

          a table of ip addresses that the hostname resolves to. For each
          address, a record (subtable) is found in the result table with
          the fields

        family
                IP protocol family, "inet" or "inet6"

        addr
                the ip address

          On error, returns nil + error message.

   tbl = lsocket.getinterfaces()
          enumerate interfaces and their addresses

    Returns

          a list containing information about all available interfaces.
          For each interface, one or more records (subtables) are found in
          the result table with the fields

        name
                interface name

        family
                IP protocol family, "inet" or "inet6"

        addr
                the ip address

        mask
                the netmask

          On error, returns nil + error message.

  Constants

   lsocket.INADDR_ANY
          IPv4 "any" address, i.e. what you bind to if you intend to
          accept connections on all addresses your computer has.

   lsocket.IN6ADDR_ANY
          IPv6 "any" address, see lsocket.INADDR_ANY.

   lsocket._VERSION
          Version number of the lsocket module.

Examples

   There are a few examples in the samples folder, including a server and
   client for tcp, udp and multicast. For all of those examples, if you
   start them without command line arguments, they work with IPv4, if
   start them with the argument 6, they work with IPv6.

Footnotes

   [2](*) The functions connect, bind, resolve and the method sendto
   transparently use name service resolution, which may block, if a name
   server is not available or slow to respond. However, name service
   resolution is not used if you pass an IP address (IPv4 or IPv6) or a
   path (unix domain) as address argument to those functions.

Verweise

   1. file:///home/gunnar/stuff/lsocket/html/README.html#fn1
   2. file:///home/gunnar/stuff/lsocket/html/README.html#r_fn1