global fio

Binary input from files with fio (file input-output)

This library provides a set of functions for reading numbers from a file and in addition to the regular io library functions.

There are eight additional little endian variants for the cardinal[1-4] and integer[1-4] readers: cardinal[1-4]le and integer[1-4]le.

Reference:

• Corresponding C source code: liolibext.c
• Source file of the LuaTeX manual: luatex-lua.tex#L655-697

😱 Types incomplete or incorrect? 🙏 Please contribute!

---

methods

---

fio.readcardinal1

---

function fio.readcardinal1(file: file*) ->  integer

@param file - A file handle.

@return - A 1 byte unsigned integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 1 byte unsigned integer (8-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(fio.readcardinal1(f), 116)
  -- e: decimal=101 hexadecimal=65 binary=01100101
  assert.equals(fio.readcardinal1(f), 101)
  -- s: decimal=115 hexadecimal=73 binary=01110011
  assert.equals(fio.readcardinal1(f), 115)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(fio.readcardinal1(f), 116)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L114-L122

fio.readcardinal2

---

function fio.readcardinal2(file: file*) ->  integer

@param file - A file handle.

@return - A 2 byte unsigned integer

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 2 byte unsigned integer (16-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  -- t.e: decimal=29797 hexadecimal=74.65 binary=01110100.01100101
  assert.equals(fio.readcardinal2(f), 29797)
  -- s.t: decimal=29556 hexadecimal=73.74 binary=01110011.01110100
  assert.equals(fio.readcardinal2(f), 29556)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L137-L147

fio.readcardinal3

---

function fio.readcardinal3(file: file*) ->  integer

@param file - A file handle.

@return - A 3 byte unsigned integer

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 3 byte unsigned integer (24-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("luatex")
  fio.setposition(f, 0)
  -- l.u.a: decimal=7107937 hexadecimal=6C.75.61 binary=01101100.01110101.01100001
  assert.equals(fio.readcardinal3(f), 7107937)
  -- t.e.x: decimal=7628152 hexadecimal=74.65.78 binary=01110100.01100101.01111000
  assert.equals(fio.readcardinal3(f), 7628152)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L187-L198

fio.readcardinal4

---

function fio.readcardinal4(file: file*) ->  integer

@param file - A file handle.

@return - A 4 byte unsigned integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 4 byte unsigned integer (32-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  -- t.e.s.t:
  -- decimal=1952805748
  -- hexadecimal=74.65.73.74
  -- binary=01110100.01100101.01110011.01110100
  assert.equals(fio.readcardinal4(f), 1952805748)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L241-L253

fio.readcardinaltable

---

function fio.readcardinaltable(
  file: file*,
  number: integer,
  bytes: (1|2|3|4)
) ->  table<integer,integer>

@param file - A file handle.

@param number - The number of integers in the resulting table.

@param bytes - Specify 1 for 1 byte unsigned integer, 2 for a 2 byte unsigned integers, and so on.

Read number unsigned integers of bytes as a table from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  local t = fio.readcardinaltable(f, 4, 1)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(t[1], 116)
  -- e: decimal=101 hexadecimal=65 binary=01100101
  assert.equals(t[2], 101)
  -- s: decimal=115 hexadecimal=73 binary=01110011
  assert.equals(t[3], 115)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(t[4], 116)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L299-363

fio.readcardinal1le

---

function fio.readcardinal1le(file: file*) ->  integer

@param file - A file handle.

Read a 1 byte unsigned little endian integer (8-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readcardinal1le(f), 116)
  assert.equals(fio.readcardinal1le(f), 101)
  assert.equals(fio.readcardinal1le(f), 115)
  assert.equals(fio.readcardinal1le(f), 116)
  assert.is_nil(fio.readcardinal1le(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L137-L147

fio.readcardinal2le

---

function fio.readcardinal2le(file: file*) ->  integer

@param file - A file handle.

Read a 2 byte unsigned little endian integer (16-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readcardinal2le(f), 25972)
  assert.equals(fio.readcardinal2le(f), 29811)
  assert.is_nil(fio.readcardinal2le(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L148-L158

little endian variant

fio.readcardinal3le

---

function fio.readcardinal3le(file: file*) ->  integer

@param file - A file handle.

Read a 3 byte unsigned little endian integer (24-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readcardinal3le(f), 7562612)
  assert.is_nil(fio.readcardinal3le(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L199-L210

little endian variant

fio.readcardinal4le

---

function fio.readcardinal4le(file: file*) ->  integer

@param file - A file handle.

Read a 4 byte unsigned little endian integer (32-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readcardinal4le(f), 1953719668)
  assert.is_nil(fio.readcardinal4le(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L254-L266

little endian variant

fio.readinteger1

---

function fio.readinteger1(file: file*) ->  integer

@param file - A file handle.

@return - A 1 byte signed integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 1 byte signed integer (8-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readinteger1(f), 116)
  assert.equals(fio.readinteger1(f), 101)
  assert.equals(fio.readinteger1(f), 115)
  assert.equals(fio.readinteger1(f), 116)
  assert.is_nil(fio.readinteger1(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L432-L442

fio.readinteger2

---

function fio.readinteger2(file: file*) ->  integer

@param file - A file handle.

@return - A 2 byte signed integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 2 byte signed integer (16-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readinteger2(f), 29797)
  assert.equals(fio.readinteger2(f), 29556)
  assert.is_nil(fio.readinteger2(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L460-L471

fio.readinteger3

---

function fio.readinteger3(file: file*) ->  integer

@param file - A file handle.

@return - A 3 byte signed integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 3 byte signed integer (24-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readinteger3(f), 7628147)
  assert.is_nil(fio.readinteger3(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L518-530

fio.readinteger4

---

function fio.readinteger4(file: file*) ->  integer

@param file - A file handle.

@return - A 4 byte signed integer.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 4 byte signed integer (32-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readinteger4(f), 1952805748)
  assert.is_nil(fio.readinteger4(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L580-593

fio.readintegertable

---

function fio.readintegertable(
  file: file*,
  number: integer,
  bytes: (1|2|3|4)
) ->  table<integer,integer>

@param file - A file handle.

@param number - The number of integers in the resulting table.

@param bytes - Specify 1 for 1 byte signed integers, 2 for a 2 byte signed integers, and so on.

Read number signed integers of bytes as a table from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)

  local t = fio.readintegertable(f, 4, 1)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(t[1], 116)
  -- e: decimal=101 hexadecimal=65 binary=01100101
  assert.equals(t[2], 101)
  -- s: decimal=115 hexadecimal=73 binary=01110011
  assert.equals(t[3], 115)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(t[4], 116)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L646-715

@see sio.readintegertable

fio.readinteger1le

---

function fio.readinteger1le(file: file*) ->  integer

@param file - A file handle.

Read a 1 byte signed little endian integer (8-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(fio.readinteger1le(f), 116)
  -- e: decimal=101 hexadecimal=65 binary=01100101
  assert.equals(fio.readinteger1le(f), 101)
  -- s: decimal=115 hexadecimal=73 binary=01110011
  assert.equals(fio.readinteger1le(f), 115)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(fio.readinteger1le(f), 116)
  f:close()
end

• Corresponding C source code: liolibext.c#L432-L442

little endian variant

fio.readinteger2le

---

function fio.readinteger2le(file: file*) ->  integer?

@param file - A file handle.

Read a 2 byte signed little endian integer (16-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readinteger2le(f), 25972)
  assert.equals(fio.readinteger2le(f), 29811)
  assert.is_nil(fio.readinteger2le(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L472-483

little endian variant

fio.readinteger3le

---

function fio.readinteger3le(file: file*) ->  integer?

@param file - A file handle.

Read a 3 byte signed little endian integer (24-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readinteger3le(f), 7562612)
  assert.is_nil(fio.readinteger3le(f))
  f:close()
end

little endian variant

Reference:

• Corresponding C source code: liolibext.c#L531-543

fio.readinteger4le

---

function fio.readinteger4le(file: file*) ->  integer?

@param file - A file handle.

Read a 4 byte signed little endian integer (32-bit) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.readinteger4le(f), 1953719668)
  assert.is_nil(fio.readinteger4le(f))
  f:close()
end

little endian variant

Reference:

• Corresponding C source code: liolibext.c#L594-607

fio.readfixed2

---

function fio.readfixed2(file: file*) ->  number?

@param file - A file handle.

@return - a 2 byte float (used in font files)

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 2 byte float (used in font files) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.numbers(fio.readfixed2(f), 116.39453125)
  assert.numbers(fio.readfixed2(f), 115.453125)
  assert.is_nil(fio.readfixed2(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L802-813

fio.readfixed4

---

function fio.readfixed4(file: file*) ->  number?

@param file - A file handle.

@return - a 4 byte float (used in font files)

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 4 byte float (used in font files) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.numbers(fio.readfixed4(f), 29797.45098877)
  assert.is_nil(fio.readfixed4(f))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L830-843

fio.read2dot14

---

function fio.read2dot14(file: file*) ->  number?

@param file - A file handle.

@return - a 2 byte float (used in font files)

😱 Types incomplete or incorrect? 🙏 Please contribute!

Read a 2 byte float (used in font files) from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.numbers(fio.read2dot14(f), 1.8186645507812)
  fio.setposition(f, 1)
  assert.numbers(fio.read2dot14(f), 1.5851440429688)
  fio.setposition(f, 2)
  assert.numbers(fio.read2dot14(f), 1.803955078125)
  assert.is_nil(sio.read2dot14("test", 4))
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L862-874
• Corresponding fontforge C source code: mem.c#L101-L107
• Corresponding fontforge C source code: ttf2eps.c#L418-L424

fio.setposition

---

function fio.setposition(
  file: file*,
  position: integer
) ->  0?

@param file - A file handle.

@return - 0 upon success, nil otherwise.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Goto position.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  assert.equals(fio.getposition(f), 0)
  assert.equals(fio.setposition(f, 3), 0)
  assert.equals(fio.getposition(f), 3)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L901-910

fio.getposition

---

function fio.getposition(file: file*) -> position integer

@param file - A file handle.

@return position - The current position in bytes.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Get the current position.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  fio.readcardinal1(f)
  assert.equals(fio.getposition(f), 1)
  fio.readcardinal1(f)
  assert.equals(fio.getposition(f), 2)
  fio.readcardinal1(f)
  assert.equals(fio.getposition(f), 3)
  fio.readcardinal1(f)
  assert.equals(fio.getposition(f), 4)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L891-899

fio.skipposition

---

function fio.skipposition(
  file: file*,
  number: integer
) ->  0?

@param file - A file handle.

@param number - The number of bytes to skip.

@return - 0 upon success, nil otherwise.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Skip number positions.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(fio.readcardinal1(f), 116)

  fio.setposition(f, 0)
  assert.equals(fio.skipposition(f, 1), 0)
  -- e: decimal=101 hexadecimal=65 binary=01100101
  assert.equals(fio.readcardinal1(f), 101)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L912-921

fio.readbytes

---

function fio.readbytes(
  file: file*,
  number: integer
) ->  integer ...

@param file - A file handle.

@param number - The number of bytes to be read.

Read number bytes from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  local b1, b2, b3, b4 = fio.readbytes(f, 4)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(b1, 116)
  -- e: decimal=101 hexadecimal=65 binary=01100101
  assert.equals(b2, 101)
  -- s: decimal=115 hexadecimal=73 binary=01110011
  assert.equals(b3, 115)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(b4, 116)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L967-980

fio.readbytetable

---

function fio.readbytetable(
  file: file*,
  number: integer
) ->  integer[]

@param file - A file handle.

@param number - The number of bytes to be read.

Read number bytes as a table from a file.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("test")
  fio.setposition(f, 0)
  local t = fio.readbytetable(f, 4)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(t[1], 116)
  -- e: decimal=101 hexadecimal=65 binary=01100101
  assert.equals(t[2], 101)
  -- s: decimal=115 hexadecimal=73 binary=01110011
  assert.equals(t[3], 115)
  -- t: decimal=116 hexadecimal=74 binary=01110100
  assert.equals(t[4], 116)
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L923-943

fio.readline

---

function fio.readline(file: file*) ->  string

@param file - A file handle.

Example:

local f = io.open("tmp.txt", "w+")
if f then
  f:write("line1\nline2\nline3\n")
  fio.setposition(f, 0)
  assert.equals(fio.readline(f), "line1")
  assert.equals(fio.readline(f), "line2")
  assert.equals(fio.readline(f), "line3")
  f:close()
end

Reference:

• Corresponding C source code: liolibext.c#L1003-1032