Library for Converting Data to and from C Structs for Lua 5.1

原创 2012年03月21日 11:24:53

Library for Converting Data to and from C Structs for Lua 5.1


This library offers basic facilities to convert Lua values to and from C structs. Its main functions are struct.pack, which packs multiple Lua values into a struct-like string; and struct.unpack, which unpacks multiple Lua values from a given struct-like string.

The fist argument to both functions is a format string, which describes the layout of the structure. The format string is a sequence of conversion elements, which respect the current endianess and the current alignment requirements. Initially, the current endianess is the machine's native endianness and the current alignment requirement is 1 (meaning no alignment at all). We can change these settings with appropriate directives in the format string.

The elements in the format string are as follows:

  • "!n" flag to set the current alignment requirement to n (necessarily a power of 2); an absent n means the machine's native alignment.
  • ">" flag to set mode to big endian.
  • "<" flag to set mode to little endian.
  • " " (empty space) ignored.
  • "x" a padding zero byte with no corresponding Lua value.
  • "b" a signed char.
  • "B" an unsigned char.
  • "h" a signed short (native size).
  • "H" an unsigned short (native size).
  • "l" a signed long (native size).
  • "L" an unsigned long (native size).
  • "in" a signed integer with n bytes (where n must be a power of 2). An absent n means the native size of an int.
  • "In" like "in" but unsigned.
  • "f" a float (native size).
  • "d" a double (native size).
  • "s" a zero-terminated string.
  • "cn" a sequence of exactly n chars corresponding to a single Lua string. An absent n means 1. When packing, the given string must have at least n characters (extra characters are discarded).
  • "c0" this is like "cn", except that the n is given by other means: When packing, n is the length of the given string; when unpacking, n is the value of the previous unpacked value (which must be a number). In that case, this previous value is not returned.


All functions are registered inside a table struct. ul>

struct.pack (fmt, d1, d2, ...)

Returns a string containing the values d1, d2, etc. packed according to the format string fmt.

struct.unpack (fmt, s, [i])

Returns the values packed in string s according to the format string fmt. An optional i marks where in s to start reading (default is 1). After the read values, this function also returns the index in s where it stopped reading, which is also where you should start to read the rest of the string.

struct.size (fmt)

Returns the size of a string formatted according to the format string fmt. For obvious reasons, the format string cannot contain neither the option s nor the option c0.


To install, simply compile the file struct.c as a dynamic library. In Linux you can use the following command:

> gcc -Wall -O2 -shared -o struct.c
In Mac, you should define the environment variable MACOSX_DEPLOYMENT_TARGET as 10.3 and then write
> gcc -bundle -undefined dynamic_lookup -Wall -O2 -o struct.c

In Windows, you must generate a DLL exporting the single symbol luaopen_struct.


  • The code print(struct.size("i")) prints the size of a machine's native int.

  • To pack and unpack the structure

    struct Str {
      char b;
      int i[4];
    in Linux/gcc/Pentium (little-endian, maximum alignment of 4), you can use the string "<!4biiii".
  • If you need to code a structure with a large array, you may use string.rep to automatically generate part of the string format. For instance, for the structure

    struct Str {
      double x;
      int i[400];
    you may build the format string with the code "d"..string.rep("i", 400).
  • To pack a string with its length coded in its first byte, use the following code:

    x = struct.pack("Bc0", string.len(s), s)
    To unpack that string, do as follows:
    s = struct.unpack("Bc0", x)
    Notice that the length (read by the element "B") is not returned.
  • Suppose we have to decode a string s with an unknown number of doubles; the end is marked by a zero value. We can use the following code:

    local a = {}
    local i = 1         -- index where to read
    while true do
      local d
      d, i = struct.unpack("d", s, i)
      if d == 0 then break end
      table.insert(a, d)
  • To pack a string in a fixed-width field with 10 characters padded with blanks, do as follows:

    x = struct.pack("c10", s .. string.rep(" ", 10))


File teststruct contains a full test script for this package. It is also a good source of examples.


This package is distributed under the MIT license. See copyright notice at the end of file struct.c.

$Id: struct.html,v 1.4 2008/04/18 20:10:24 roberto Exp $

SQL Script for select data from ebs and make a csv file to FTP

DECLARE CURSOR cur_lcy_test IS SELECT rcta.customer_trx_id, rcta.trx_number, rcta.trx_date ...

HowTo compile native C codes to a library for iOS development in Xcode – take Mosquitto as an exampl

HowTo compile native C codes to a library for iOS development in Xcode – take Mosquitto as an exampl...

Script to Collect Data Guard Primary Site Diagnostic Information for Version 10g and above(+RAC)

-- NAME: new_dg_prim_diag.sql  (Run from sqlplus on PRIMARY with a LOGICAL or PHYSICAL STANDBY as SY...

From C to C++: A quick reference for aging programmers

一篇比较精炼的从C到C++语言语法过度的博文,尽管不完美,但值得借鉴。 转自: So you were a great sys...
  • 2011年10月18日 10:30
  • 650

Script to Collect Data Guard Physical and Active Standby Diagnostic Info for 10g and above(+RAC)

-- NAME: new_dg_psby_diag.sql (Run from sqlplus on PHYSICAL STANDBY, ACTIVE STANDBY as SYS) -- ----...

How to Install Dev-C++ and the GLUT Libraries for Compiling OpenGL Programs with ANSI C

How to Install Dev-C++ and the GLUT Libraries for Compiling OpenGL Programs with ANSI C (versio...

decruft(A library to extract meaningful data from a webpage) 源码分析

开源Python模块, decruft使用example, from decruft import Document #import...

How to distribute your own Android library through jCenter and Maven Central from Android Studio

In Android Studio, if you wish to include any library to your application. You could just simply add...
您举报文章:Library for Converting Data to and from C Structs for Lua 5.1