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 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 bi- nary, 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 op- tional 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 configura- tion cannot be deleted without deleting the target. add_target_kv name key value Define or update a key/value pair assoicated with the specific tar- get. 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 spe- cific 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 ac- cessible from the context of a specific arcan application matching applname and is intended for application specific persistent config- uration. 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 asso- ciated 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 associ- ated with the configs as well. drop_target targetname Delete the specific target and all associated configurations, envi- ronment 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 inter- faces 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 exter- nal 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 pro- gram 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/con- figuration 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 ig- nored. For GAME, the fsrv_game frameserver will be used as a chainloader. The tar- get executable with be expanded into the core to be run, the first (op- tional) 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 serializa- tion 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 re- sourcepath might also be relevant. COPYRIGHT Copyright A(C) 2014-2018 Bjorn Stahl. License 3-clause BSD. This is free software: you are free to change and redistribute it. There is NO WAR- RANTY, 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+15.1.quarterly>