vrosnet / lsocket Goto Github PK

                                     README

lsocket

   A library that provides network programming support for Lua.

   Author: Gunnar Zötl , 2013.
   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 and IPv6, 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(), 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.1 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.

        address
                (optional) ip address or hostname to bind to, defaults to
                lsocket.INADDR_ANY ('0.0.0.0').

        port
                port number to bind to

        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.

        address
                ip address or hostname to connect to

        port
                port number to connect to

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

    Returns

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

  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 none 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 what is "socket", return information about the local
            socket. Fields as for "peer"

   sock, ip, 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.

          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 3 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.

    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

          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.

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) as
   address argument to those functions.

References

   1. file://localhost/home/u871670/tmp/lsocket/README.html#fn1
   2. file://localhost/home/u871670/tmp/lsocket/README.html#r_fn1