Module atomvm

AtomVM-specific APIs.

Description

This module contains functions that are specific to the AtomVM platform.

Data Types

avm_path()


avm_path() = iodata()

platform_name()


platform_name() = generic_unix | emscripten | esp32 | pico | stm32

posix_error()


posix_error() = atom() | integer()

posix_open_flag()


posix_open_flag() = o_exec | o_rdonly | o_rdwr | o_search | o_wronly | o_append | o_cloexec | o_creat | o_directory | o_dsync | o_excl | o_noctty | o_nofollow | o_rsync | o_sync | o_trunc | o_tty_atom

Function Index

add_avm_pack_binary/2	Add code from an AVM binary to your application.
add_avm_pack_file/2	Add code from an AVM binary to your application.
close_avm_pack/2	Close previously opened AVM binary from your application.
get_start_beam/1	Get the start beam for a given avm.
platform/0	Return the platform moniker.
posix_clock_settime/2	Set the system time.
posix_close/1	Close a file that was opened with `posix_open/2,3`
posix_open/2	Open a file (on platforms that have `open(3)`).
posix_open/3	Open a file (on platforms that have `open(3)`).
posix_read/2	Read at most `Count` bytes from a file.
posix_write/2	Write data to a file.
rand_bytes/1	Returns a binary containing random sequence of bytes of length Len.
random/0	Returns a random 32-bit integer value.
read_priv/2	This function allows to fetch priv/ resources content.

Function Details

add_avm_pack_binary/2


add_avm_pack_binary(AVMData::binary(), Options::[{name, Name::atom()}]) -> ok | {error, any()}

AVMData: AVM data.
Options: Options, as a property list.

returns: ok

Add code from an AVM binary to your application.

This function will add the data in the AVMData parameter to your application. The data is assumed to be valid AVM data (e.g, as generated by packbeam tooling).

Failure to properly load AVM data is result in a runtime error

add_avm_pack_file/2


add_avm_pack_file(AVMPath::avm_path(), Options::[{name, Name::atom()}]) -> ok | {error, any()}

AVMPath: Path to AVM data.
Options: Options, as a property list.

returns: ok

Add code from an AVM binary to your application.

This function will add the data located in the AVMPath parameter to your application. The data is assumed to be valid AVM data (e.g, as generated by packbeam tooling).

On generic_unix platforms, the AVMPath may be a valid file system path to an AVM file.

On esp32 platforms, the AVMPath should be the name of an ESP32 flash partition, prefixed with the string /dev/partition/by-name/. Thus, for example, if you specify /dev/partition/by-name/main2.app as the AVMPath, the ESP32 flash should contain a data partition with the name main2.app

Failure to properly load AVM path is result in a runtime error

close_avm_pack/2


close_avm_pack(Name::atom(), Options::[]) -> ok | error

Options: Options, as a property list.

returns: ok | error

Close previously opened AVM binary from your application.

This function will close the data referenced by the Name parameter from your application. The Name parameter must reference previously opened AVM data.

Failure to close AVM data is result in a runtime error

get_start_beam/1


get_start_beam(AVM::atom()) -> {ok, binary()} | {error, not_found}

AVM: Name of avm (atom)

returns: the name of the start module (with suffix)

Get the start beam for a given avm

platform/0


platform() -> platform_name()

returns: The platform name.

Return the platform moniker. You may use this function to uniquely identify the platform type on which your application is running.

posix_clock_settime/2


posix_clock_settime(ClockId::realtime, ValueSinceUnixEpoch::{Seconds::integer(), Nanoseconds::integer()}) -> ok | {error, Reason::posix_error()}

ClockId: The clock id
ValueSinceUnixEpoch: The value, in specified seconds and nanoseconds, since the UNIX epoch (Jan 1, 1970)

returns: ok or an error tuple

Set the system time.

This function sets the system time to the specified value, expressed as a tuple containing seconds and nanoseconds since the UNIX epoch (Jan 1, 1970). Coordinates are all in UTC.

Note. Some systems may require special permissions to call this function.

posix_close/1


posix_close(File::posix_fd()) -> ok | {error, posix_error()}

File: Descriptor to a file to close

returns: ok or an error tuple

Close a file that was opened with posix_open/2,3

posix_open/2


posix_open(Path::iodata(), Flags::[posix_open_flag()]) -> {ok, posix_fd()} | {error, posix_error()}

Path: Path to the file to open
Flags: List of flags passed to open(3).

returns: A tuple with a file descriptor or an error tuple.

Open a file (on platforms that have open(3)). The file is automatically closed when the file descriptor is garbage collected.

Files are automatically opened with O_NONBLOCK. Other flags can be passed.

posix_open/3


posix_open(Path::iodata(), Flags::[posix_open_flag()], Mode::non_neg_integer()) -> {ok, posix_fd()} | {error, posix_error()}

Path: Path to the file to open
Flags: List of flags passed to open(3).
Mode: Mode passed to open(3) for created file.

returns: A tuple with a file descriptor or an error tuple.

Open a file (on platforms that have open(3)). This variant can be used to specify the mode for new file.

posix_read/2


posix_read(File::posix_fd(), Count::non_neg_integer()) -> {ok, binary()} | eof | {error, posix_error()}

File: Descriptor to an open file
Count: Maximum number of bytes to read

returns: a tuple with read bytes, eof or an error tuple

Read at most Count bytes from a file. Files are open non-blocking. ˋatomvm:posix_select_read/3’ can be used to determine if the file can be read. eof is returned if no more data can be read because the file cursor reached the end.

posix_write/2


posix_write(File::posix_fd(), Data::binary()) -> {ok, non_neg_integer()} | {error, posix_error()}

File: Descriptor to an open file
Data: Data to write

returns: a tuple with the number of written bytes or an error tuple

Write data to a file. Files are open non-blocking. ˋatomvm:posix_select_write/3’ can be used to determine if the file can be written.

rand_bytes/1


rand_bytes(Len::non_neg_integer()) -> binary()

Len: non-negative integer

returns: Binary containing random sequence of bytes of length Len.

Returns a binary containing random sequence of bytes of length Len. Supplying a negative value will result in a badarg error. This function will use a cryptographically strong RNG if available. Otherwise, the random value is generated using a PRNG.

random/0


random() -> integer()

returns: random 32-bit integer.

Returns a random 32-bit integer value. This function will use a cryptographically strong RNG if available. Otherwise, the random value is generated using a PRNG.

read_priv/2


read_priv(App::atom(), Path::list()) -> binary()

App: application name.
Path: path to the resource.

returns: Binary containing the resource content.

This function allows to fetch priv/ resources content.