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

FreeBSD Manual Pages


home | help
Tcl_RegisterConfig(3)	    Tcl	Library	Procedures	 Tcl_RegisterConfig(3)


       Tcl_RegisterConfig  - procedures	to register embedded configuration in-

       #include	<tcl.h>

       Tcl_RegisterConfig(interp, pkgName, configuration, valEncoding)

       Tcl_Interp *interp (in)		       Refers to the  interpreter  the
					       embedded	configuration informa-
					       tion is	registered  for.  Must
					       not be NULL.

       const char *pkgName (in)		       Contains	 the name of the pack-
					       age  registering	 the  embedded
					       configuration  as ASCII string.
					       This means that	this  informa-
					       tion  is	in UTF-8 too. Must not
					       be NULL.

       const Tcl_Config	*configuration (in)    Refers to an array of  Tcl_Con-
					       fig  entries containing the in-
					       formation embedded in  the  bi-
					       nary library. Must not be NULL.
					       The end of the  array  is  sig-
					       naled by	either a key identical
					       to NULL,	or a key referring  to
					       the empty string.

       const char *valEncoding (in)	       Contains	the name of the	encod-
					       ing used	to store the  configu-
					       ration  values as ASCII string.
					       This means that	this  informa-
					       tion  is	in UTF-8 too. Must not
					       be NULL.

       The function described here has its base	in TIP 59 and provides	exten-
       sions  with support for the embedding of	configuration information into
       their binary library and	the generation of a  Tcl-level	interface  for
       querying	this information.

       To  embed configuration information into	their binary library an	exten-
       sion has	to define a non-volatile array of Tcl_Config entries in	one if
       its  source files and then call Tcl_RegisterConfig to register that in-

       Tcl_RegisterConfig takes	four arguments;	first, a reference to the  in-
       terpreter  we are registering the information with, second, the name of
       the package registering its configuration information, third, a pointer
       to  an  array of	structures, and	fourth a string	declaring the encoding
       used by the configuration values.

       The string valEncoding contains the name	of an encoding known  to  Tcl.
       All  these  names  are use only characters in the ASCII subset of UTF-8
       and are thus implicitly in the UTF-8 encoding. It is expected that keys
       are legible English text	and therefore using the	ASCII subset of	UTF-8.
       In other	words, they are	expected to be in UTF-8	too. The values	 asso-
       ciated  with the	keys can be any	string however.	For these the contents
       of valEncoding define which encoding was	used to	represent the  charac-
       ters of the strings.

       Each  element of	the configuration array	refers to two strings contain-
       ing the key and the value associated with that key. The end of the  ar-
       ray  is signaled	by either an empty key or a key	identical to NULL. The
       function	makes no copy of the configuration array. This means that  the
       caller has to make sure that the	memory holding this array is never re-
       leased. This is the meaning behind the word non-volatile	used  earlier.
       The  easiest  way to accomplish this is to define a global static array
       of Tcl_Config entries. See the  file  "generic/tclPkgConfig.c"  in  the
       sources of the Tcl core for an example.

       When called Tcl_RegisterConfig will

       (1)    create  a	 namespace having the provided pkgName,	if not yet ex-

       (2)    create the command pkgconfig in that namespace and  link	it  to
	      the provided information so that the keys	from configuration and
	      their associated values can be retrieved through calls  to  pkg-

       The command pkgconfig will provide two subcommands, list	and get:

	      ::pkgName::pkgconfig list
		     Returns a list containing the names of all	defined	keys.

	      ::pkgName::pkgconfig get key
		     Returns the configuration value associated	with the spec-
		     ified key.

       The Tcl_Config structure	contains the following fields:

	      typedef struct Tcl_Config	{
		  const	char *key;
		  const	char *value;
	      }	Tcl_Config;

       embedding, configuration, binary	library

Tcl				      8.4		 Tcl_RegisterConfig(3)


Want to link to this manual page? Use this URL:

home | help