Home Contents | # Opening files | Rawio | Core4 Lua Event System

## SYNOPSIS

#include <lua/fcntl.lh>

1. handle = rawio.open(filename [, mode])
2. handle = rawio.attach(fd)

## DESCRIPTION

Both functions return a rawio handle instance for use with other rawio functions. rawio.open() opens the file or device at filename, while rawio.attach() initializes a handle from an already open file descriptor.

The optional mode parameter consists of the logical or of one access mode and optional flags. The default is O_RDWR | O_CREAT.

Access modes
O_RDONLY | Open file for reading.
O_WRONLY | Open file for writing.
O_RDWR | Open for both reading and writing.

Flags
O_CREAT | If the file does not exist, it will be created.
O_TRUNC | If the file already exists, it is truncated to zero length.
O_APPEND | Before each write, the file pointer is placed at the end of the file.
O_NONBLOCK | The file is opened in nonblocking mode. No subsequent operation on the open file will cause the calling process to wait. Instead, all functions that would cause a wait will instead return an error indicating that condition. This flag must be set if the file handle is to be used with an event loop, or your application might suffer from unexpected lockups.
O_SILENT | Only useful for serial ports. When set, the control signals CTS and DTR are not initialized after opening the port, but left in the state they where before. This flag is Core4 kernel specific.

## RETURN VALUE

On success, a rawio handle is returned. On error, three values are returned: nil, a string describing the error (The result of the C library call strerror() on the errno code) and the errno number from the standard C library.

## NOTES

Useful pre-existing file descriptors for use with rawio.attach() are 0 (Standard input), 1 (Standard output), 2 (Standard error output).

## EXAMPLE

Opening the second serial port.

> >
#include <lua/fcntl.lh> ser = rawio.open("dev/ttyS1", O_RDWR | O_NONBLOCK | O_SILENT)

A somewhat obfuscated way of saying hello.

> >
handle = rawio.attach(1) handle:write("Hello World\n")
Hello World

## SEE ALSO

rawio:blocking, rawio:canReadLine, rawio:clearError, rawio:close, rawio:connect, rawio:detach, rawio:lastError, rawio:line, rawio:lines, rawio.access, rawio:read, rawio:copy, rawio.stat, rawio.statfs, rawio:writet, rawio:write