arcan(1)

NAME
Arcan - Scriptable Multimedia Engine

SYNOPSIS
arcan [OPTIONS] applname [APPLARGS]

DESCRIPTION
Arcan is a portable and fast self-sufficient multimedia engine for advanced visualization and analysis work in a wide range of applications e.g. game development, real-time streaming video, monitoring and surveillance, up to and including desktop compositors and window managers.

OPTIONS

-h, --help
    Show a brief summary of commands and usage.

-w, --width pixels
    Set the desired active canvas width. Setting this value to zero will let the display driver chose based on connected displays. This can be overridden by the running appl. This value will be cached/fetched from the database.

-h, --height pixels
    Set the desired active canvas height. Setting this value to zero will let the display driver chose based on connected displays. This can be overridden by the running appl. This value will be cached/fetched from the database.

-m, --conservative
    Toggle conservative memory management profile. The engine will store just enough metadata to be able to reconstruct static data sources (e.g. most textures, fonts etc.) should the display context need to be rebuilt. Note that the behaviors of this option may vary radically depending on video platform. Verify and Validate heavily when using conservative mode.

-W, --sync-strat strategy
    Specify the synchronization strategy that the display driver should use initially. These are dependent on the built-time configuration of the engine and are listed at the end of running arcan with the --help command-line argument.

-M, --monitor rate
    Enable monitoring mode, every rate ticks, save a snapshot of the scripting engine state to a monitoring target (see -O, --monitor-out). If the rate is set to a negative value, only script errors will be written.

-O, --monitor-out target
    Defines the monitoring data recipient, used in combination with -M, --monitor. Either specify LOG:filename or LOGFD:fdno for a file destination or inherited file descriptor number.

-C, --monitor-ctrlilename or -
    Sets filename (use - for stdin) to work as a blocking control interface / watchdog that is triggered upon sending SIGUSR1 to the process. This can preempt script execution and is intended as an internal developer facing channel for building better inspection and debugging tools. Refer to the source implementation for arcan_monitor.c for commands and processing.

-p, --rpath path
    Change default searchpath for shared resources, see the namespaces section below for additional details.

-B, --binpath path
    Specify the full path to the desired frameserver (e.g. /usr/bin/arcan_frameserver) or to a prefix /path/to/prefix_ (decode, encode, game, terminal, remoting).

-L, --libpath path
    Set the search path for native libraries (used e.g. by lua system_load).

-t, --applpath path
    Change default searchpath for applications, see the namespaces section below for additional details.

-T, --scriptpath path
    Change the default search path for builtin system scripts, see the namespaces section below for additional details.

-H, --hook
    Specify a post-init (after running applname()) hook script that will be loaded and executed. The scripts are fetched from the system scripts namespace (-T, --scriptpath). Providing multiple -H arguments is allowed. See the hookscripts section below for additional details.

-b, --fallback applname
    If the running application crashes due to scripting error or from misuse of the API, all running external or recoverable frameserver, connections will be transferred to applname. If applname is set to the reserved value :self the same appl will be used without running a verifyload cycle.

-d, --database dbname
    Specify a different database for use when launching external targets and as a key/value store for the running application, overriding the default of HOMEDIR/.arcan/arcan.sqlite.

-g, --debug
    Increases debuglevel, more troubleshooting data will be sent to the standard error and standard output nodes. The active debuglevel is also exposed to scripts. This can be added multiple times for additional effect. Debuglevels over 2 enabled engine features that change engine behavior and notably increases verbosity.

-V, --version
    Print a version string to stdout and then terminate. This version string can be used to identify the build, including audio, video, input platforms and source code repository checkout id.

-1, --pipe-stdout
    This is only usable from an arcan_lwa instance. A requested connection point is generated and written to stdin. This is supposed to be used with a normal arcan instance running piped with -0 and act as a generic mechanism for hooking up multiple arcan instances in a pipes-and-filters structure.

-0, --pipe-stdin
    See the description for 'pipe-stdin'. Reads a single line from stdin and tries to open an external connection point with that name (assuming it passes normal connection point validation).

Unstable Arguments
    These are slated to be replaced with a more flexible display configuration system and will be changed in coming versions. Users should therefore take precautions to make sure to notice when upgrading as not to break scripts that depend on these features.

-S, --nosound
    Disable (silence) audio output.

-s, --windowed
    Set borderless, windowed display mode.

-f, --fullscreen
    Fullscreen switch, the display driver will attempt to force the connected display resolution to match the specified canvas dimensions.

-a, --multisamples samples
    Enable multisampling (MSAA), default: 4 samples. If MSAA setup fails, the engine will silently revert to regular sampling. There is also a range of possible environment variables for tuning options related to the various input platforms. These are printed when you start arcan with the --help argument and vary depending on how the engine was compiled.

USER-NAMESPACES
For dynamically exposing files and folders with user controlled petnames and access restructions, the database and the 'arcan' appl key value store is used. This is mainly useful / intended for cases where Arcan is used as the system display server and desktop. The keys and values follows the format: key=ns_petname value=Label:permissions:path. As an example, exposing the user home directory on a POSIX system would be: arcan_db add_appl_kv arcan ns_home Home:rw:/home/me This is intended to be controlled / managed by dynamic tools, like an external drive or encrypted storage mounting daemon.

NAMESPACES
There is a large assortment of namespaces that the engine will search for when an appl requests read access to- or the creation of- a resource. The way these are set up will vary depending on command-line arguments, operating-system specific scans, if applname was specified as a relative/absolute path and on a series of environment variables. For a more detailed explanation on how this works from an appl developer perspective, please refer to the developer documentation on the wiki. This setup is rather complex in order to account for a large range of platforms and use-cases, with the most simple configuration being an application base folder (controlled with the -t command-line switch) and a shared resource folder (Controlled with the -p switch). The most important namespaces are the APPLBASE and the RESOURCEPATH. Appls can manipulate (create, open, read, write) the files within the confines of the APPLBASE/APPNAME. Traversal (../) outside this path will be blocked, but a user can explicitly map (symlink, bind-mounts or similar) other paths into this namespace and the engine will allow it. Scripts are treated as an overlay namespace where there is a priority order in the event of a collision. By default, scripts are treated in the order of APPLTEMP -> APPLBASE -> SCRIPTPATH. More paranoid builds will want to disable APPLTEMP to prevent the creation of a unpacker scripts / code generation. The most fine-grained control can be obtained by setting a number of environment variables:

ARCAN_RESOURCEPATH
    Shared resources, as described above.

ARCAN_SCRIPTPATH
    The system script namespace contains shared scripts that are part of the general Arcan package to promote optional re-use of higher level analysis like mouse gestures. The default search-path for this is would be the share/arcan/scripts install path, though you might want to override this for custom setups or development purposes.

ARCAN_APPLTEMPPATH
    Used when there is a need to split the folder that an appl can use as a writable (delete, create, update) backing store. By default, this is resolved to the same folder as the appl is - but can be unmapped to prevent an appl from killing or modifying itself.

ARCAN_APPLBASEPATH
    This path is used to search for appls but may be ignored for absolute paths specified on the command-line.

ARCAN_APPLSTOREPATH
    The default setting is to allow the appl full access to its own folder, but this can be split into a separate store. This will then expand as ARCAN_APPLSTOREPATH/APPLNAME.

ARCAN_STATEBASEPATH
    The default setting is to map this to RESOURCEPATH/savestates and will then be shared between all appls (which holds true whenever STATEBASE is set to a subdirectory of RESOURCEPATH).

ARCAN_FONTPATH
    The default setting is to map this to the APPLPATH/fonts with fallback to RESOURCEPATH/fonts but can be set to some other system font directory for more fine-grained control (as font-parsing is complex and can be a source of vulnerabilities).

ARCAN_BINPATH
    The default is to set this to /usr/bin/arcan_frameserver (or wherever the frameserver is installed, first searching ./ then /usr/local/bin then /usr/bin).

ARCAN_LIBPATH
    This path specifies the directory where the appl is allowed to load libraries from using system_load. The namespace is referenced as RESOURCE_SYS_LIBS in the scripting documentation.

ARCAN_LOGPATH
    Set to RESOURCEPATH/logs by default (if it exists) and is used for storing debugging, profiling and similar development/troubleshooting related data. This includes state dumps which may contain sensitive data. Some namespaces are also reset when an appl does an explicit switch, this behavior can be cancelled out by setting ARCAN_XXXPIN for any namespaces that should explicitly be locked to some path.

FRAMESERVERS
A principal design decision behind Arcan is to split tasks that are inherently prone to security and stability issues into separate processes that should be sandboxed to as large a degree as possible with the principle of least privilege in mind. These behave like 'normal' clients but are grouped into fixed roles (archetypes), like 'decode' is responsible for image parsing and so on. They are chainloaded by 'arcan_frameserver' into its respective role (afsrv_) based on a probe done at startup, a build-time mask and an environment controlled mask. For instance, to block the 'terminal' role, set AFSRV_BLOCK_TERMINAL. It should be the active application (set of user-supplied scripts) that dynamically control the level of privilege, communication and data storage that such processes have access to. These are mainly an internal developer detail, some scripting functions transparently set them up - e.g. launch_decode(...) and define_recordtarget(...).

LIGHTWEIGHT (LWA) ARCAN
Lightweight arcan is a specialized build of the engine that uses the frameserver shared memory API as its audio/video display backend. This allows Arcan to run and control additional instances of itself, with the same or a different application, thus reusing the engine to fulfill the role of application framework, rendering engine and display server all rolled into one. The lwa build works just the same (although likely with fewer dependencies on external libraries) as the main version, except the ARCAN_CONNPATH environment need to be set to a connection point that the arcan instance exposes.

HEADLESS ARCAN
Headless arcan is a specialized build of the engine that performs all rendering in memory, and normally do not try to output anything to the screen. It adds the option to use other software defined outputs via the capabilities of the encode frameserver. By setting the video platform argument for ARCAN_VIDEO_ENCODE=encode_args, the output can be recorded or streamed, interactively as well as non-interactively. See the afsrv_encode binary for the possible encoding options. A special detail with this build is that, since there is no strict output, the default virtual display dimensions have to be set explicitly via the -w and -h arguments.

HOOK SCRIPTS
There is a built-in set of more generic and re-usable scripts being distributed along with the engine. These are normally installed as a 'scripts' subdirectory in the shared set of files, though this path can be changed with the -T argument. A hookscript is enabled via the -H command line argument, which can be repeated to chain them together. Their arguments are extracted from the appl-arguments part of the command line in the key=value form.

hook/shutdown.lua
    This hookscript sets a timer to whatever a shutdown=number argument on the commandline provides, or the built-in default of 500 ticks. When the timer fires, an asynchronous shutdown request will be queued. This allows for easier automation and testing.

hook/external_input.lua
    This hookscript opens up a connection point where you can attach external input drivers. The default connection point for the first hook script will be extio_1, this will increment for each instance of the script that is added to the command line. The extio prefix can be tuned by adding the ext_io key to the database for the specific appl being run, and only one input provider can be attached to the connection point at a time.

hook/timed_dump.lua
    This script sets a timer to whatever dump_timer=number or dump_periodic=number on the command-line is set to. When the timer fires, it calls system_snapshot into 'timed_n.lua" or whatever dump_prefix is set to on the command-line. The _n suffix corresponds to the dump sequence if on a periodic timer.

hook/debugstall.lua
    This scripts enables the frameserver debugstall (delay whenever a frameserver is launched) as a tool to make it easier to attach a debugger to it. The delay can be configured through debugstall=val (default is 10) on the command- line.

hook/alloc_debug
    This scripts intercepts all allocation functions and attaches a debug traceback as the 'tag' property of the video object. This can then be used in system_snapshot and crash-dumps to figure out where a certain allocation came from.

hook/touch_simulator.lua
    This script takes over mouse input and re-injects as touch input. Since it intercepts the input appl- handler, it is best used as a pre: hook rather than the default (post).

DIAGNOSTICS
There are a number of ways the engine can shut down, especially if the engine was built in Debug mode. A governing principle for user supplied scripts is that of Fail Often, Early and Hard. This means that API misuse, i.e. missing or wrong arguments will result in a crash and the related error description will be provided (color-coded) to the standard output, and that a state dump will be generated and stored in the namespace specified by ARCAN_LOGPATH. This state dump is a Lua parsable script that can be loaded either by a regular Lua interpreter. The environment variable ARCAN_FRAMESERVER_DEBUGSTALL can be set if you suspect that a frameserver is involved, or to blame, for an issue. This will print the process ID (pid) of the new frameserver process to standard output, then sleep for the argument supplied number of seconds, to provide enough time to attach a debugger or tracing tool. There is also a way to trace the events that are passed between the main process and all the framesevers, and that is via the environment variable ARCAN_SHMIF_DEBUG=1.

HOMEPAGE
https://arcan-fe.com

SEE-ALSO
arcan_api_overview(3) arcan_lwa(1) arcan_frameserver(1) arcan_db(1)

BUGS
You can report bugs through the tracker on the github page. For normal contact and discussion, see the #arcan IRC channel on freenode. Save a snapshot of core-dumps (in the case of engine issues) or the appropriate resources/logs entries. For some issues, a copy of the database used and a list of files (with permissions) in applpath and resourcepath may also be relevant.

COPYRIGHT
Copyright © 2003-2020 Bjorn Stahl. License GPLv2+ or BSD depending on build configuration. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

AUTHOR
Bjorn Stahl <contact at arcan-fe dot com>