main-apidocs-erlang-eavmlib-atomvm.md
AtomVM-specific APIs.
This module contains functions that are specific to the AtomVM platform.
avm_path() = iodata()
platform_name() = generic_unix | emscripten | esp32 | pico | stm32
abstract datatype : posix_dir()
posix_error() = atom() | integer()
abstract datatype : posix_fd()
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
posix_stat_info() = #{st_dev => integer(), st_ino => integer(), st_mode => integer(), st_nlink => integer(), st_uid => integer(), st_gid => integer(), st_size => integer(), st_atime_s => integer(), st_mtime_s => integer(), st_ctime_s => integer()}
posix_whence() = seek_set | seek_cur | seek_end
| 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_fstat/1 | Get file status from a file descriptor using fstat(2). |
| posix_fsync/1 | Flush file data to storage using fsync(2). |
| posix_ftruncate/2 | Truncate a file to a specified length using ftruncate(2). |
| posix_mkdir/2 | Create a directory using mkdir(2). |
| posix_mkfifo/2 | Create a FIFO special file (named pipe) using mkfifo(2). |
| 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_pread/3 | Read at most Count bytes from a file at a given offset using pread(2). |
| posix_pwrite/3 | Write data to a file at a given offset using pwrite(2). |
| 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_rename/2 | |
| posix_rmdir/1 | Remove an empty directory using rmdir(2). |
| posix_seek/3 | Reposition the file cursor using lseek(2). |
| posix_stat/1 | Get file status using stat(2). |
| 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. |
| subprocess/4 | Fork and execute a program using fork(2) and execve(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(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(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(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() -> 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(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(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(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_fstat(File::posix_fd()) -> {ok, posix_stat_info()} | {error, posix_error()}
File: Descriptor to an open file
returns: a tuple with a map of file information or an error tuple
Get file status from a file descriptor using fstat(2).
posix_fsync(File::posix_fd()) -> ok | {error, posix_error()}
File: Descriptor to an open file
returns: ok or an error tuple
Flush file data to storage using fsync(2).
posix_ftruncate(File::posix_fd(), Length::non_neg_integer()) -> ok | {error, posix_error()}
File: Descriptor to an open file
Length: Desired file length in bytes
returns: ok or an error tuple
Truncate a file to a specified length using ftruncate(2). If the file is larger than Length, the extra data is lost. If the file is shorter, it is extended with null bytes.
posix_mkdir(Path::iodata(), Mode::non_neg_integer()) -> ok | {error, posix_error()}
Path: Path to the directory to create
Mode: Permission bits for the new directory
returns: ok or an error tuple
Create a directory using mkdir(2).
posix_mkfifo(Path::iodata(), Mode::non_neg_integer()) -> ok | {error, posix_error()}
Path: Path to the new FIFO special file
Mode: Permission bits for the new FIFO
returns: ok or an error tuple
Create a FIFO special file (named pipe) using mkfifo(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(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_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_pread(File::posix_fd(), Count::non_neg_integer(), Offset::non_neg_integer()) -> {ok, binary()} | eof | {error, posix_error()}
File: Descriptor to an open file
Count: Maximum number of bytes to read
Offset: Offset in bytes from the start of the file
returns: a tuple with read bytes, eof or an error tuple
Read at most Count bytes from a file at a given offset using pread(2). The file cursor is not modified.
posix_pwrite(File::posix_fd(), Data::binary(), Offset::non_neg_integer()) -> {ok, non_neg_integer()} | {error, posix_error()}
File: Descriptor to an open file
Data: Data to write
Offset: Offset in bytes from the start of the file
returns: a tuple with the number of written bytes or an error tuple
Write data to a file at a given offset using pwrite(2). The file cursor is not modified.
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_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_rename(OldPath::iodata(), NewPath::iodata()) -> ok | {error, posix_error()}
posix_rmdir(Path::iodata()) -> ok | {error, posix_error()}
Path: Path to the directory to remove
returns: ok or an error tuple
Remove an empty directory using rmdir(2).
posix_seek(File::posix_fd(), Offset::integer(), Whence::posix_whence()) -> {ok, integer()} | {error, posix_error()}
File: Descriptor to an open file
Offset: Offset in bytes
Whence: Reference point for the offset
returns: a tuple with the resulting absolute offset or an error tuple
Reposition the file cursor using lseek(2).
posix_stat(Path::iodata()) -> {ok, posix_stat_info()} | {error, posix_error()}
Path: Path to the file
returns: a tuple with a map of file information or an error tuple
Get file status using stat(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(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() -> 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(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.
subprocess(Path::iodata(), Args::[iodata()], Env::[iodata()] | undefined, Options::[stdout]) -> {ok, non_neg_integer(), posix_fd()} | {error, posix_error()}
Path: path to the command to execute
Args: arguments to pass to the command. First item is the name of the command
Options: options to run execve. Should be [stdout]
returns: a tuple with the process id and a fd to the stdout of the process.
Fork and execute a program using fork(2) and execve(2). Pipe stdout so output of the program can be read with atomvm:posix_read/2.