FreeBSD Manual Pages
arcan(1) User manual 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 applica- tion 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 in- stance 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 in- stance 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 ref- erence 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 BI- NARY FORMATS below for details. The optional tag argument speci- fies 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 config- uration 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 li- braries 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 argu- ments 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 configura- tion 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 per- sistent 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 spe- cific 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 man- age 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 other- wise 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 re- placed with the respective namespace expansion. Libs will, in turn, be added to the LD_PRELOAD, DYLD_INSERT_LIBRARIES or some other implemen- tation 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 se- mantic meaning (and is internally aliased as BIN) but reserved for fu- ture use. For EXTERNAL, the BIN expansion rules apply, but indicate that the en- gine should suspend all operations (or maintain an audio/video/frame- server- 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 se- rialization or interfacing tool, interface with the arcan_db.c / ar- can_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 AU- THOR contact below. Save a snapshot of core-dumps (in the case of en- gine issues) or the appropriate resources/logs entries. For some is- sues, a copy of the database used and a list of files (with permis- sions) 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> arcan_db October 2015 arcan(1)
NAME | SYNOPSIS | DESCRIPTION | COMMAND | TAGS | SCRIPTING MODE | BINARY FORMATS | NOTES | SEE-ALSO | BUGS | COPYRIGHT | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=arcan_db&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>