README

lsocket

A library that provides network programming support for Lua.

Author: Gunnar Zötl, 2013-2023.
Released under the terms of the MIT 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. 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. 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.4, 5.3.0 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. luarocks uses this Makefile to build lsocket.

Using

Load the module with:

lsocket = require "lsocket"

Constructors

Socket Methods

Functions

Constants

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.