xstr(1)								      xstr(1)



NAME
  xstr - Extracts strings from C programs to implement shared strings

SYNOPSIS

  xstr [-c] [file | -]

  The xstr command maintains a file called strings into which strings in com-
  ponent parts of a large program are hashed.

FLAGS

  -c  Extracts strings from the specified file.

DESCRIPTION

  The strings extracted by xstr are replaced with references to this array.
  This serves to implement shared constant strings, most useful if they are
  also read-only.

  The following command extracts the strings from the C source in file,
  replacing string references by expressions of the form (&xstr[number]) for
  some number.

       xstr -c file


  The xstr command uses file as input; the resulting C text is placed in the
  file x.c to then be compiled.	 The strings from this file are appended to
  the strings file if they are not there already.  Repeated strings and
  strings that are suffixes of existing strings do not cause changes to the
  file.

  If a string is a suffix of another string in the file, but the shorter
  string is seen first by xstr, both strings are placed in the file strings.

  After all components of a large program are compiled, a file xs.c declaring
  the common xstr space can be created by a command of the following form:

       xstr


  Compile and load this xs.c file with the rest of the program.	 Some C com-
  pilers may, by default, put strings in a read-only text section.

  The xstr command can also be used on a single file.  The following command
  creates files x.c and xs.c as before, without using or affecting a strings
  file in the same directory.

       xstr file

  It may be useful to run xstr after the C preprocessor if any macro defini-
  tions yield strings or if there is conditional code that contains strings
  that may not be needed.  The xstr command reads from its standard input
  when the argument - (dash) is given.	An appropriate command sequence for
  running xstr after the C preprocessor is as follows:

       cc -E file.c | xstr -c -
       cc -c x.c
       mv x.o file.o


  The xstr command does not touch the file strings unless new items are
  added, thus make can avoid remaking xs.o unless truly necessary.

EXAMPLES

   1.  To extract the strings from the C source in the file.c parameter,
       replacing string references by expressions of the form
       (&xstr[number]), enter:
	    xstr -c file

       An appropriate declaration of the xstr array is prepended to file.
       The resulting C text is placed in the file x.c, to then be compiled.

   2.  To declare the common xstr array space in the xs.c file, enter:
	    xstr


FILES

  strings
	 File that contains the extracted strings.

  x.c	 Modified C source.

  xs.c	 C source for definition of array xstr.

  /tmp/xs*
	 Temporary file when the xstr command does not touch strings.

RELATED INFORMATION

  Commands:  mkstr(1).