14.14.1.1 open

The open builtin allows you to create new IO spaces, by opening an IO device. It has the following prototype:

fun open = (string handler, uint<64> flags = 0) int<32>

where handler is a string identifying the IO device that will serve the IO space. This handler can be:

*name*

An auto growing memory buffer.

pid://[0-9]+

The process ID of some process.

/path/to/file

An either absolute or relative path to a file.

nbd://host:port/export

nbd+unix:///export?socket=/path/to/socket

A connection to an NBD server. See nbd command

flags is a bitmask that specifies several aspects of the operation, including the mode in which the IO space is opened. Its value is usually built by ORing a set of flags that are provided by the compiler. These are:

IOS_F_READ

The IO space is intended to be read.

IOS_F_WRITE

The IO space is intended to be written.

IOS_F_TRUNCATE

The IO space shall be truncated upon opening.

IOS_F_CREATE

If the IO device doesn’t exist, then create it, usually empty.

Note that the specific meanings of these flags depend on the on the nature of the IO space that is opened: for example, it is optional whether a file is truncated, but a memory buffer is truncated by default, and an NBD iospace does not support truncation.

In order to ease the usage of open, a few pre-made bitmaps are provided to specify opening modes:

IOS_M_RDONLY

This is equivalent to IOS_F_READ.

IOS_M_WRONLY

This is equivalent to IOS_F_WRITE.

IOS_M_RDWR

This is equivalent to IOS_F_READ | IOS_F_WRITE.

The open builtin returns a signed 32-bit integer. This number will identify the just opened IOS until it gets closed.

If there is a problem opening the specified IO device then open will raise an E_no_ios exception.