24.16.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

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_CREATE

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

Note that the specific behaviour of these flags depend on the nature of the IO space that is opened. For example a memory buffer is always truncated at creation by default.

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 non-negative signed 32-bit integer. This number will identify the just opened IOS until it gets closed. The IO space identifiers are allocated sequentially, and are consistently re-used. This means, for example, that to the sequence open; open; open; close (1); open; the following IO spaces get allocated: 0, 1, 2, 1.

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