Manual Pages for UNIX Operating System command usage for man xstr

User Commands                                             xstr(1)



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

SYNOPSIS
     xstr -c filename [-v] [-l array]


     xstr [-l array]


     xstr filename [-v] [-l array]


DESCRIPTION
     xstr maintains a file called strings into which  strings  in
     component parts of a large program are hashed. These strings
     are replaced with  references  to  this  common  area.  This
     serves  to implement shared constant strings, which are most
     useful if they are also read-only.


     The command:

       example% xstr -c filename




     extracts the strings from the C source  in  name,  replacing
     string  references  by expressions of the form &xstr[number]
     for some number.  An  appropriate  declaration  of  xstr  is
     prepended  to  the  file.  The resulting C text is placed in
     the file x.c, to then be compiled.  The  strings  from  this
     file  are  placed  in  the strings data base if they are not
     there already. Repeated strings and strings which  are  suf-
     fixes  of  existing strings do not cause changes to the data
     base.


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

       example% xstr




     This xs.c file should then be compiled and loaded  with  the
     rest  of  the  program.   If possible, the array can be made
     read-only (shared) saving space and swap overhead.



SunOS 5.11          Last change: 14 Sep 1992                    1






User Commands                                             xstr(1)



     xstr can also be used on a single file.  A command:


     example% xstr filename


     creates files x.c and  xs.c  as  before,  without  using  or
     affecting any strings file in the same directory.


     It may be useful to run xstr after the C preprocessor if any
     macro  definitions  yield strings or if there is conditional
     code which contains strings  which  may  not,  in  fact,  be
     needed. xstr reads from the standard input when the argument
     `-' is given. An appropriate command  sequence  for  running
     xstr after the C preprocessor is:

       example% cc -E name.c | xstr -c -
       example% cc -c x.c
       example% mv x.o name.o




     xstr does not touch the file strings unless  new  items  are
     added;  thus  make(1S)  can avoid remaking xs.o unless truly
     necessary.

OPTIONS
     -c filename       Take C source text from filename.


     -v                Verbose: display a progress  report  indi-
                       cating where new or duplicate strings were
                       found.


     -l array          Specify the named  array in program refer-
                       ences  to abstracted strings.  The default
                       array name is xstr.


FILES
     strings     data base of strings


     x.c         massaged C source


     xs.c        C source for definition of array "xstr*(rq





SunOS 5.11          Last change: 14 Sep 1992                    2






User Commands                                             xstr(1)



     /tmp/xs*    temp  file  when  xstr  filename  doesn't  touch
                 strings


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcs                      |
    |_____________________________|_____________________________|


SEE ALSO
     make(1S), attributes(5)

BUGS
     If a string is a suffix of another string in the data  base,
     but  the  shorter  string is seen first by xstr both strings
     will be placed in the  data  base,  when  just  placing  the
     longer one there would do.

NOTES
     Be aware that xstr  indiscriminately  replaces  all  strings
     with expressions of the form &xstr[number] regardless of the
     way the original C code might have  used  the  string.   For
     example,  you  will encounter a problem with  code that uses
     sizeof() to determine the length of a literal string because
     xstr  will  replace  the  literal string with a pointer that
     most likely will have a different size than the string's.


     To circumvent this problem:

         o    use  strlen()  instead  of   sizeof();  note   that
              sizeof()  returns  the size of the array (including
              the null byte at the end), whereas strlen() doesn't
              count    the   null   byte.   The   equivalent   of
              sizeof("xxx") really is (strlen("xxx"))+1.

         o    use #define for operands of sizeof()  and  use  the
              define'd  version. xstr ignores #define statements.
              Make sure you run xstr on filename before  you  run
              it on the preprocessor.


     You will also encounter a problem when declaring an initial-
     ized character array of the form



SunOS 5.11          Last change: 14 Sep 1992                    3






User Commands                                             xstr(1)



       char x[] = "xxx";




     xstr will replace   xxx  with  an  expression  of  the  form
     &xstr[number]  which  will  not compile.  To circumvent this
     problem, use static char *x = "xxx" instead of  static  char
     x[] = "xxx".














































SunOS 5.11          Last change: 14 Sep 1992                    4