arcan(1)

NAME
Arcan_db - Database Support tool for Arcan

SYNOPSIS
arcan_db [-d dbfile] [COMMAND] command-specific data

DESCRIPTION
The arcan_db tool manages the database that arcan uses as an application specific key-value store, but also for controlling which programs (targets) and which set of arguments (configuration) that are allowed to be launched by an application using Arcan. It is also used to manage some configuration options for the arcan instance itself. Such options are stored under the reserved appl names "arcan" and "arcan_lwa" respectively. It is also used to manage some configuration options for the arcan instance itself. Such options are stored under the reserved appl names "arcan" and "arcan_lwa" respectively.

COMMAND

add_target name -tag bfrm executable argv
    Create a new target or update values for a pre-existing ones. The name field is a unique identifier that will be used to reference the target from within the engine. executable should point to the binary, folder or specific data file to be launched. bfrm specifies the binary format to be loaded, where BIN corresponds to a native binary (e.g. ELF for POSIX systems and PE on windows), LWA for using arcan-in-arcan style execution and RETRO for a libretro- compatible core (.so or .dll).see BINARY FORMATS below for details. The optional tag argument specifies ONE application defined selection tag. See the section on tags below for further guidance. Argv can be a variable number of arguments that will be set as the base arguments for the target. For bfrm LWA, these will be passed to the application and will be ignored for bfrm RETRO. A configuration named default will also be created, this configuration cannot be deleted without deleting the target.

add_target_kv name key value
    Define or update a key/value pair assoicated with the specific target. These values are also accessible from the context of an arcan application.

add_target_env targetname key value
    Add a key/value pair (expands to key=value internally) that will be used to set up the environment for the program. Those that are specific for library interposition, e.g. LD_PRELOAD may be filtered and the _target_lib command should be used for such purposes.

add_target_lib targetname libstr
    Add a library for interpositioning, 'hijack'. These are libraries used to replace specific function calls in the subject. The specific mechanism for accomplishing this is implementation defined.

add_config targetname configname argv
    Create or update configname in the specific target. The arguments specified in argv are similar to those used in add_target but will always be appended after the arguments associated with the target.

add_config_kv targetname configname key val
    Add a key/value pair associated with a configuration. This pair will be accessible from the context of an arcan application, and may be used by an arcan application to track client configuration specific settings.

add_config_env targetname configname ey val
    Add a key/value pair associated with a configuration. This pair will be accessible from the environment of the executing client.

add_appl_kv applname key val
    Add a key/value pair associated with an appl. This pair will be accessible from the context of a specific arcan application matching applname and is intended for application specific persistent configuration.

drop_appl_key applname key
    Remove the key and value from the specified appl.

drop_config targetname configname
    Delete a specific config. This will also remove any key/values associated with that config. The configname 'default' cannot be removed in this way.

drop_all_configs targetname
    Delete all configs for the specific target. This act as a "for each config in target, drop_config" and will thus purge the keys associated with the configs as well.

drop_target targetname
    Delete the specific target and all associated configurations, environment library and key/value pairs.

drop_appl applname
    Delete all keys associated with the specific application name.

TAGS
Each target can be associated with a tag. These have application specific meaning, though a generalized suggested set of tags that are also respected by hook-scripts where applicable are as follows: autorun - Should be used to select targets that should be launched upon startup, this includes all configurations attached to that target. hidden - Should be used to prevent targets from being listed in user interfaces that allows the user to pick targets that can be launched. autorun_hidden - Combines the behavior from the tag 'autorun' and from the tag 'hidden'. This is suggested for hook scripts that want to manage external connection points that should be invisible to the running application.

SCRIPTING MODE
To assist when using this program as a database interface for a script, a single dash can be specified instead of the command. In that case, the program will process line- separated input from STDIN where each element is separated with a tab character. The command format is otherwise the same as regular usage. In addition, the program will output 'OK' or 'FAIL' to stderr in response to each command (while stdout will contained the more detailed error description).

BINARY FORMATS
The currently supported binary formats are BIN, LWA, SHELL, EXTERNAL and GAME. Binary format specifies how the new process will be created when launching a target/configuration pair. For BIN, the argv, envv and libs are treated with expanding namespaces. This means that all entries will have [ARCAN_XXXPATH] fields being replaced with the respective namespace expansion. Libs will, in turn, be added to the LD_PRELOAD, DYLD_INSERT_LIBRARIES or some other implementation defined hijack/interposition technique. (Corresponding fields may be fileted from env). For SHELL, the BIN expansion rules apply, but indicate that it should be launched / monitored as a shell. This currently has no further semantic meaning (and is internally aliased as BIN) but reserved for future use. For EXTERNAL, the BIN expansion rules apply, but indicate that the engine should suspend all operations (or maintain an audio/video/frameserver- less pipeline) and release as much resources as possible, until the target/configuration has finished executing. For LWA, (currently not implemented, scheduled for 0.6) arcan_lwa will be used as a loader, with similar expansion to envv. Libs- list will be ignored. For GAME, the fsrv_game frameserver will be used as a chainloader. The target executable with be expanded into the core to be run, the first (optional) argument aded to the configuration will be the resource to pass on and the seocond (also optional) argument defines the system- path.

NOTES
There is also a number of list/show_ commands that are listed if you run the program without any arguments. These are not intended as a serialization or interfacing tool, interface with the arcan_db.c / arcan_db.h for those kinds of purposes.

SEE-ALSO
arcan(1)

BUGS
You can report bugs at the forum on the homepage or through the the AUTHOR contact below. 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 might also be relevant.

COPYRIGHT
Copyright © 2014-2018 Bjorn Stahl. License 3-clause BSD. 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>