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_dir()
abstract datatype: posix_dir()
posix_error()
posix_error() = atom() | integer()
posix_fd()
abstract datatype: posix_fd()
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_closedir/1 | Close a directory that was opened with posix_opendir/1 |
| 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_opendir/1 | Open a file (on platforms that have opendir(3)). |
| posix_read/2 | Read at most Count bytes from a file. |
| posix_readdir/1 | Read a directory entry
eof is returned if no more data can be read because the directory cursor
reached the end. |
| posix_write/2 | Write data to a file. |
| rand_bytes/1 | (Deprecated.) 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
Name: the AVM name.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 idValueSinceUnixEpoch: 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_closedir/1
posix_closedir(Dir::posix_dir()) -> ok | {error, posix_error()}
Dir: Descriptor to a directory to close
returns: ok or an error tuple
Close a directory that was opened with posix_opendir/1
posix_open/2
posix_open(Path::iodata(), Flags::[posix_open_flag()]) -> {ok, posix_fd()} | {error, posix_error()}
Path: Path to the file to openFlags: 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 openFlags: 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_opendir/1
posix_opendir(Path::iodata()) -> {ok, posix_dir()} | {error, posix_error()}
Path: Path to the directory to open
returns: A tuple with a directory descriptor or an error tuple.
Open a file (on platforms that have opendir(3)).
posix_read/2
posix_read(File::posix_fd(), Count::non_neg_integer()) -> {ok, binary()} | eof | {error, posix_error()}
File: Descriptor to an open fileCount: 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_readdir/1
posix_readdir(Dir::posix_dir()) -> {ok, {dirent, Inode::integer(), Name::binary()}} | eof | {error, posix_error()}
Dir: Descriptor to an open directory
returns: a {dirent, InodeNo, Name} tuple, eof or an error tuple
Read a directory entry
eof is returned if no more data can be read because the directory 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 fileData: 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.
This function is deprecated: Use crypto:strong_rand_bytes/1 instead.
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.