arcan(1)

📦 version 0.7.1, in nixos 26.05, nixpkgs unstable

✨ NAME ✨

Arcan_db — Database Support tool for Arcan. This is the arcan(1) manual page, bestie 💖

🌸 SYNOPSIS 🌸

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

💖 DESCRIPTION 💖

Okay so arcan_db is the tool that manages the database arcan uses as an application specific key-value store, and it also controls which programs (targets) and which set of arguments (configuration) are allowed to be launched by an application using Arcan. Slay.

It also manages some configuration options for the arcan instance itself. Those options are stored under the reserved appl names "arcan" and "arcan_lwa" respectively. Periodt.

And because the original page literally says the next bit twice, I’m giving it to you twice too, no cap:

It also manages some configuration options for the arcan instance itself. Those options are stored under the reserved appl names "arcan" and "arcan_lwa" respectively. Yes bestie, same energy again 💅

🎀 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 associated 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. (Yes, the signature literally says ey val; I am not fixing the manpage, I’m just delivering it with sparkle 💀)
  • 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 acts 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). Bestie, it really says “contained” in the original and I’m keeping the vibe honest 😭

🔥 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.

  • 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).
  • 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.
  • 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.
  • 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.
  • GAME — The fsrv_game frameserver will be used as a chainloader. The target executable will be expanded into the core to be run, the first (optional) argument added to the configuration will be the resource to pass on and the second (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 🌈

💀 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 © 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>

Cute sign-off time, bestie: footer vibes are source/version arcan_db, date October 2015, manual arcan(1) — mwah, bye 🫶✨

📦 where this page comes from