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

FreeBSD Manual Pages

  
 
  

home | help
XrmGetResource(3)		XLIB FUNCTIONS		     XrmGetResource(3)

NAME
       XrmGetResource,	XrmQGetResource,  XrmQGetSearchList,  XrmQGetSearchRe-
       source -	retrieve database resources and	search lists

SYNTAX
       #include	<X11/Xresource.h>

       Bool  XrmGetResource(XrmDatabase	  database,   char   *str_name,	  char
	      *str_class, char **str_type_return, XrmValue *value_return);

       Bool XrmQGetResource(XrmDatabase	database, XrmNameList quark_name, Xrm-
	      ClassList	quark_class, XrmRepresentation *quark_type_return, Xr-
	      mValue *value_return);

       typedef XrmHashTable *XrmSearchList;

	      Bool  XrmQGetSearchList(XrmDatabase database, XrmNameList	names,
	      XrmClassList    classes,	  XrmSearchList	   list_return,	   int
	      list_length);

       Bool  XrmQGetSearchResource(XrmSearchList  list,	XrmName	name, XrmClass
	      class, XrmRepresentation *type_return, XrmValue *value_return);

ARGUMENTS
       class	 Specifies the resource	class.

       classes	 Specifies a list of resource classes.

       database	 Specifies the database	that is	to be used.

       list	 Specifies the search list returned by XrmQGetSearchList.

       list_length
		 Specifies the number of entries (not the byte size) allocated
		 for list_return.

       list_return
		 Returns a search list for further use.

       name	 Specifies the resource	name.

       names	 Specifies a list of resource names.

       quark_class
		 Specifies  the	 fully	qualified class	of the value being re-
		 trieved (as a quark).

       quark_name
		 Specifies the fully qualified name of	the  value  being  re-
		 trieved (as a quark).

       quark_type_return
		 Returns  the  representation  type  of	 the destination (as a
		 quark).

       str_class Specifies the fully qualified class of	the  value  being  re-
		 trieved (as a string).

       str_name	 Specifies  the	 fully	qualified  name	of the value being re-
		 trieved (as a string).

       str_type_return
		 Returns the representation type  of  the  destination	(as  a
		 string).

       type_return
		 Returns data representation type.

       value_return
		 Returns the value in the database.

DESCRIPTION
       The  XrmGetResource  and	 XrmQGetResource functions retrieve a resource
       from the	specified database.  Both take a  fully	 qualified  name/class
       pair, a destination resource representation, and	the address of a value
       (size/address pair).  The value and returned type point	into  database
       memory; therefore, you must not modify the data.

       The  database  only  frees or overwrites	entries	on XrmPutResource, Xr-
       mQPutResource, or XrmMergeDatabases.  A client that is not storing  new
       values  into the	database or is not merging the database	should be safe
       using the address passed	back at	any time until it  exits.   If	a  re-
       source  was found, both XrmGetResource and XrmQGetResource return True;
       otherwise, they return False.

       The XrmQGetSearchList function takes a list of names  and  classes  and
       returns	a  list	of database levels where a match might occur.  The re-
       turned list is in best-to-worst order and uses the  same	 algorithm  as
       XrmGetResource  for  determining	 precedence.  If list_return was large
       enough for the search list, XrmQGetSearchList returns True;  otherwise,
       it returns False.

       The  size of the	search list that the caller must allocate is dependent
       upon the	number of levels and wildcards in the resource specifiers that
       are  stored in the database.  The worst case length is %3 sup n%, where
       n is the	number of name or class	components in names or classes.

       When using XrmQGetSearchList followed by	multiple probes	for  resources
       with  a	common name and	class prefix, only the common prefix should be
       specified in the	name and class list to XrmQGetSearchList.

       The XrmQGetSearchResource function searches the specified database lev-
       els for the resource that is fully identified by	the specified name and
       class.  The search stops	with the first	match.	 XrmQGetSearchResource
       returns True if the resource was	found; otherwise, it returns False.

       A  call	to XrmQGetSearchList with a name and class list	containing all
       but the last component of a resource name followed by  a	 call  to  Xr-
       mQGetSearchResource  with the last component name and class returns the
       same database entry as  XrmGetResource  and  XrmQGetResource  with  the
       fully qualified name and	class.

MATCHING RULES
       The  algorithm  for determining which resource database entry matches a
       given query is the heart	of the resource	 manager.   All	 queries  must
       fully  specify  the  name and class of the desired resource (use	of the
       characters "*" and "?" are not permitted).  The library supports	up  to
       100  components	in  a full name	or class.  Resources are stored	in the
       database	with only partially specified names and	classes, using pattern
       matching	constructs.  An	asterisk (*) is	a loose	binding	and is used to
       represent any number of intervening components, including none.	A  pe-
       riod  (.)  is a tight binding and is used to separate immediately adja-
       cent components.	 A question mark (?) is	used to	match any single  com-
       ponent  name or class.  A database entry	cannot end in a	loose binding;
       the final component (which cannot be the	character "?") must be	speci-
       fied.   The  lookup  algorithm searches the database for	the entry that
       most closely matches (is	most specific for) the full name and class be-
       ing  queried.   When more than one database entry matches the full name
       and class, precedence rules are used to select just one.

       The full	name and class are scanned from	left to	 right	(from  highest
       level  in  the  hierarchy to lowest), one component at a	time.  At each
       level, the corresponding	component and/or binding of each matching  en-
       try  is determined, and these matching components and bindings are com-
       pared according to precedence rules.  Each of the rules is  applied  at
       each level before moving	to the next level, until a rule	selects	a sin-
       gle entry over all others.  The rules, in order of precedence, are:

       1.   An entry that contains a matching component	(whether name,	class,
	    or	the  character	"?")  takes precedence over entries that elide
	    the	level (that is,	entries	that match the level in	a loose	 bind-
	    ing).

       2.   An	entry  with a matching name takes precedence over both entries
	    with a matching class and entries that match using	the  character
	    "?".  An entry with	a matching class takes precedence over entries
	    that match using the character "?".

       3.   An entry preceded by a tight binding takes precedence over entries
	    preceded by	a loose	binding.

SEE ALSO
       XrmInitialize(3),  XrmMergeDatabases(3),	 XrmPutResource(3), XrmUnique-
       Quark(3)
       Xlib - C	Language X Interface

X Version 11			 libX11	1.6.12		     XrmGetResource(3)

NAME | SYNTAX | ARGUMENTS | DESCRIPTION | MATCHING RULES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XrmGetResource&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help