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  li-
					       brary.  Must  not  be NULL. The
					       end of the array	is signaled by
					       either a	key identical to NULL,
					       or a key	referring to the empty

       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 library and the generation	of a Tcl-level interface for  querying
       this information.

       To  embed configuration information into	their library an extension 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 informa-

       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, library

Tcl				      8.4		 Tcl_RegisterConfig(3)


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

home | help