lsh

• Index

Contents

• Functions
• Fh methods

Modules

• lsh
• lsh.cmd
• lsh.cmd.child
• lsh.cmd.status
• lsh.fio
• lsh.fio.fh
• lsh.memfd
• lsh.path
• lsh.pipeline
• lsh.pipeline.children
• lsh.pipeline.pstatus
• lsh.stringx
• lsh.time

Topics

• README

Examples

• cmd_spec.lua
• helper.lua
• libc_spec.lua
• memfd_spec.lua
• nofile_spec.lua
• path_spec.lua
• pipeline_spec.lua
• stringx_spec.lua

Module lsh.fio.fh

File input/output handle.

Functions

new (fd)

Constructs a new file handle.

Fh methods

type ()	Returns the instance type.
close (self)	Closes the file handle.
read_to_buf (self, buf, len)	Reads from the file handle into the given buffer.
read (self[, len])	Reads from the file handle.
write (self, buf[, len])	Writes to the file handle.
seek (self, position)	Sets the position for the next read or write.
lines (self)	Returns an iterator function.
getfd (self)	Returns the file descriptor number.

Functions

new (fd)

Constructs a new file handle.

You do not need to call this function directly. Use lsh.memfd or lsh.fio.open.

Parameters:

• fd cdata ljsyscall fd

Returns:

lsh.fio.fh new fh instance

Usage:

local sh = require 'lsh'

local fh = sh.memfd()

Fh methods

type ()

Returns the instance type.

Returns:

the string "fh"

Usage:

local sh = require 'lsh'

assert(sh.open('/dev/null'):type() == 'fh')

close (self)

Closes the file handle.

Parameters:

• self lsh.fio.fh

Returns:

bool true

Or

1. nil
2. string error

Usage:

local sh = require 'lsh'

assert(sh.open('/dev/null'):close())

read_to_buf (self, buf, len)

Reads from the file handle into the given buffer.

This low-level interface is for micro-optimizations. For usual reads, see read.

Parameters:

• self lsh.fio.fh
• buf cdata buffer to read into
• len number length of the buffer

Returns:

number the number of bytes read into buffer

Or

1. nil
2. string error

Usage:

local sh = require 'lsh'
local ffi = require 'ffi'

local buf_len = 4096
local buf = ffi.new('char[?]', buf_len)

local in_fh = sh.open('in.txt', 'rdonly', 'RUSR')
local out_fh = sh.open('out.txt', {'creat', 'wronly'}, {'RUSR', 'WUSR'})

repeat
  local len = in_fh:read_to_buf(buf, buf_len)
  out_fh:write(buf, len)
until len <= 0

read (self[, len])

Reads from the file handle.

Parameters:

• self lsh.fio.fh
• len number maximum number of bytes to read (optional)

Returns:

string the data that was read

Or

1. nil
2. string error

Usage:

local sh = require 'lsh'

local zeros = sh.open('/dev/zero'):read(3)
assert(#zeros == 3)

write (self, buf[, len])

Writes to the file handle.

Parameters:

• self lsh.fio.fh
• buf cdata or string buffer to write
• len int length of the buffer (required if buf is cdata) (optional)

Returns:

bool true

Or

1. nil
2. string error

Usage:

local sh = require 'lsh'

assert(sh.open('/dev/null', 'wronly'):write('abc'))

-- advanced usage, passing cdata pointers
local ffi = require 'ffi'
local str = 'abc'
local buf = ffi.new('char[?]', #str, str)
assert(sh.open('/dev/null', 'wronly'):write(buf, #str))

seek (self, position)

Sets the position for the next read or write.

This interface is not final. It will change in incompatible ways.

Parameters:

• self lsh.fio.fh
• position number

Returns:

number position

Usage:

local sh = require 'lsh'

local position = sh.open('/dev/zero'):seek(3)

lines (self)

Returns an iterator function. Each call returns the next line from the file handle, without the line ending.

Parameters:

• self lsh.fio.fh

Returns:

func function iterator

Usage:

local sh = require 'lsh'

for line in sh.memfd('foo\nbar'):lines() do
  print(line)
end
--> foo
--> bar

getfd (self)

Returns the file descriptor number.

Parameters:

• self lsh.fio.fh

Returns:

number file descriptor number

Usage:

local sh = require 'lsh'

print(sh.open('/dev/null'):getfd())
--> 3