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

FreeBSD Manual Pages


home | help
exstr(1)			 User Commands			      exstr(1)

       exstr - extract strings from source files

       exstr filename...

       exstr -e	filename...

       exstr -r	[-d] filename...

       The  exstr  utility  is	used to	extract	strings	from C-language	source
       files and replace them by calls to the message retrieval	function  (see
       gettxt(3C)). This utility will extract all character strings surrounded
       by double quotes, not just strings used as arguments to the printf com-
       mand  or	the printf routine. In the first form, exstr finds all strings
       in the source files and writes them on the standard output. Each	string
       is preceded by the source file name and a colon (:).

       The first step is to use	exstr -e to extract a list of strings and save
       it in a file. Next, examine this	list and determine which  strings  can
       be translated and subsequently retrieved	by the message retrieval func-
       tion. Then, modify this file by deleting	lines that can't be translated
       and, for	lines that can be translated, by adding	the message file names
       and the message numbers as the fourth (msgfile) and fifth (msgnum)  en-
       tries  on  a  line.  The	 message files named must have been created by
       mkmsgs(1) and exist in /usr/lib/locale/locale/LC_MESSAGES   . (The  di-
       rectory	locale	corresponds  to	the language in	which the text strings
       are written; see	setlocale(3C)).	The message numbers used  must	corre-
       spond to	the sequence numbers of	strings	in the message files.

       Now  use	 this modified file as input to	exstr -r to produce a new ver-
       sion of the original C-language source file in which the	 strings  have
       been  replaced by calls to the message retrieval	function gettxt(). The
       msgfile and msgnum fields are used to construct the first  argument  to
       gettxt(). The second argument to	gettxt() is printed if the message re-
       trieval fails at	run-time. This argument	is the null string, unless the
       -d option is used.

       This  utility  cannot  replace strings in all instances.	For example, a
       static initialized character string cannot be replaced  by  a  function
       call. A second example is that a	string could be	in a form of an	escape
       sequence	which could not	be translated. In order	not to break  existing
       code, the files created by invoking exstr -e must be examined and lines
       containing strings not replaceable by function calls must  be  deleted.
       In some cases the code may require modifications	so that	strings	can be
       extracted and replaced by calls to the message retrieval	function.

       The following options are supported:

       -e	Extract	a list of strings from	the  named  C-language	source
		files,	with  positional information. This list	is produced on
		standard output	in the following format:


		file		the name of a C-language source	file

		line		line number in the file

		position	character position in the line

		msgfile		null

		msgnum		null

		string		the extracted text string

		Normally you would redirect this output	into a file. Then  you
		would edit this	file to	add the	values you want	to use for ms-
		gfile and msgnum:

		msgfile		the file that contains the text	 strings  that
				will  replace  string.	A  file	with this name
				must be	created	and installed in the appropri-
				ate place by the mkmsgs(1) utility.

		msgnum		the sequence number of the string in msgfile.

		The next step is to use	exstr -r to replace strings in file.

       -r	Replace	 strings  in  a	 C-language  source file with function
		calls to the message retrieval function	gettxt().

       -d	This option is used together with the -r option. If  the  mes-
		sage  retrieval	 fails	when  gettxt() is invoked at run-time,
		then the extracted string is printed. You would	use the	 capa-
		bility	provided by exstr on an	application program that needs
		to run in an international environment and have	messages print
		in  more  than	one language. exstr replaces text strings with
		function calls that point at strings in	a message  data	 base.
		The  data  base	 used  depends	on  the	 run-time value	of the
		LC_MESSAGES environment	variable (see environ(5)).

       Example 1: The following	examples show uses of exstr

       Assume that the file example.c contains two strings:



	       printf("This is an example\n");

	       printf("Hello world!\n");


       The exstr utility, invoked with the argument example.c extracts strings
       from the	named file and prints them on the standard output.

       example%	exstr example.c

       produces	the following output:

       example.c:This is an example\n
       example.c:Hello world!\n

       The  exstr  utility,  invoked with the -e option	and the	argument exam-
       ple.c, and redirecting output to	the file example.stringsout

       example%	exstr -e example.c > example.stringsout

       produces	the following output in	the file example.stringsout

       example.c:3:8:::This is an example\n
       example.c:4:8:::Hello world!\n

       You must	edit example.stringsout	to add the values you want to use  for
       the  msgfile  and msgnum	fields before these strings can	be replaced by
       calls to	the retrieval function.	If UX is the name of the message file,
       and the numbers 1 and 2 represent the sequence number of	the strings in
       the file, here is what example.stringsout looks like after you add this

       example.c:3:8:UX:1:This is an example\n
       example.c:4:8:UX:2:Hello	world!\n

       The  exstr utility can now be invoked with the -r option	to replace the
       strings in the source file by calls to the message  retrieval  function

       example%	exstr -r example.c <example.stringsout >intlexample.c

       produces	the following output:

       extern char *gettxt();



	    printf(gettxt("UX:1", ""));

	    printf(gettxt("UX:2", ""));


       The following example:

       example%	exstr -rd example.c <example.stringsout	>intlexample.c

       uses the	extracted strings as a second argument to gettxt():

       extern char *gettxt();



	       printf(gettxt("UX:1", "This is an example\n"));

	       printf(gettxt("UX:2", "Hello world!\n"));



	   files created by mkmsgs(1)

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWtoo			   |

       gettxt(1),  mkmsgs(1),  printf(1),  srchtxt(1), gettxt(3C), printf(3C),
       setlocale(3C), attributes(5), environ(5)

       The error messages produced by exstr are	intended to  be	 self-explana-
       tory. They indicate errors in the command line or format	errors encoun-
       tered within the	input file.

SunOS 5.10			  5 Jul	1990			      exstr(1)


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

home | help