Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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)

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>

home | help