_O_n_l_i_n_e _M_a_n_u_a_l             User Commands                  exstr(1)



NNNNAAAAMMMMEEEE
     exstr - extract strings from source files

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     eeeexxxxssssttttrrrr _f_i_l_e...
     eeeexxxxssssttttrrrr ----eeee _f_i_l_e...
     eeeexxxxssssttttrrrr ----rrrr [----dddd] _f_i_l_e...

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The _e_x_s_t_r utility is used to extract strings from C-language
     source files and replace them by calls to the message
     retrieval function (see _g_e_t_t_x_t(3)).  This utility will
     extract all character strings surrounded by double quotes,
     not just strings used as arguments to the _p_r_i_n_t_f command or
     the _p_r_i_n_t_f routine.  In the first form, _e_x_s_t_r 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 meanings of the options are:

     ----eeee      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:

                 _f_i_l_e:_l_i_n_e:_p_o_s_i_t_i_o_n:_m_s_g_f_i_l_e:_m_s_g_n_u_m:_s_t_r_i_n_g

                 _f_i_l_e      the name of a C-language source file
                 _l_i_n_e      line number in the file
                 _p_o_s_i_t_i_o_n  character position in the line
                 _m_s_g_f_i_l_e   null
                 _m_s_g_n_u_m    null
                 _s_t_r_i_n_g    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 _m_s_g_f_i_l_e and _m_s_g_n_u_m:

                 _m_s_g_f_i_l_e   the file that contains the text
                           strings that will replace _s_t_r_i_n_g.  A
                           file with this name must be created
                           and installed in the appropriate place
                           by the _m_k_m_s_g_s(1) utility.

                 _m_s_g_n_u_m    the sequence number of the string in
                           _m_s_g_f_i_l_e.

             The next step is to use _e_x_s_t_r -_r to replace _s_t_r_i_n_gs
             in _f_i_l_e.

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

     ----dddd      This option is used together with the ----rrrr option.  If
             the message retrieval fails when _g_e_t_t_x_t() is invoked
             at run-time, then the extracted string is printed.

     You would use the capability provided by _e_x_s_t_r on an appli-
     cation program that needs to run in an international






     environment and have messages print in more than one
     language.  _e_x_s_t_r 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.

     The first step is to use _e_x_s_t_r -_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 function.  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 (_m_s_g_f_i_l_e) and
     fifth (_m_s_g_n_u_m) entries on a line.  The message files named
     must have been created by _m_k_m_s_g_s(1) and exist in
     ////uuuussssrrrr////lllliiiibbbb////llllooooccccaaaalllleeee////_l_o_c_a_l_e////LLLLCCCC____MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS.  (The directory _l_o_c_a_l_e
     corresponds to the language in which the text strings are
     written; see _s_e_t_l_o_c_a_l_e(3)).  The message numbers used must
     correspond to the sequence numbers of strings in the message
     files.

     Now use this modified file as input to _e_x_s_t_r -_r to produce a
     new version of the original C-language source file in which
     the strings have been replaced by calls to the message
     retrieval function _g_e_t_t_x_t().  The _m_s_g_f_i_l_e and _m_s_g_n_u_m fields
     are used to construct the first argument to _g_e_t_t_x_t().  The
     second argument to _g_e_t_t_x_t() is printed if the message
     retrieval fails at run-time.  This argument is the null
     string, unless the ----dddd 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 _e_x_s_t_r -_e must be examined and
     lines containing strings not replaceable by function calls
     must be deleted. In some cases the code may require modifi-
     cations so that strings can be extracted and replaced by
     calls to the message retrieval function.

EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     The following examples show uses of _e_x_s_t_r.

     Assume that the file ffffoooooooo....cccc contains two strings:

          main()
          {
               printf("This is an example\n");
               printf("Hello world!\n");
          }

     The _e_x_s_t_r utility, invoked with the argument ffffoooooooo....cccc extracts
     strings from the named file and prints them on the standard
     output.

     eeeexxxxssssttttrrrr ffffoooooooo....cccc produces the following output:

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






     eeeexxxxssssttttrrrr ----eeee ffffoooooooo....cccc >>>> ffffoooooooo....ssssttttrrrriiiinnnnggggssssoooouuuutttt produces the following out-
     put in the file ffffoooooooo....ssssttttrrrriiiinnnnggggssssoooouuuutttt:

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

     You must edit ffffoooooooo....ssssttttrrrriiiinnnnggggssssoooouuuutttt to add the values you want to
     use for the _m_s_g_f_i_l_e and _m_s_g_n_u_m fields before these strings
     can be replaced by calls to the retrieval function.  If UUUUXXXX
     is the name of the message file, and the numbers 1111 and 2222
     represent the sequence number of the strings in the file,
     here is what ffffoooooooo....ssssttttrrrriiiinnnnggggssssoooouuuutttt looks like after you add this
     information:

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

     The _e_x_s_t_r utility can now be invoked with the ----rrrr option to
     replace the strings in the source file by calls to the mes-
     sage retrieval function _g_e_t_t_x_t().

     eeeexxxxssssttttrrrr ----rrrr ffffoooooooo....cccc <<<<ffffoooooooo....ssssttttrrrriiiinnnnggggssssoooouuuutttt >>>>iiiinnnnttttllllffffoooooooo....cccc produces the fol-
     lowing output:

          extern char *gettxt();
          main()
          {
               printf(gettxt("UX:1", ""));
               printf(gettxt("UX:2", ""));
          }

     eeeexxxxssssttttrrrr ----rrrrdddd ffffoooooooo....cccc <<<<ffffoooooooo....ssssttttrrrriiiinnnnggggssssoooouuuutttt >>>>iiiinnnnttttllllffffoooooooo....cccc uses the
     extracted strings as a second argument to _g_e_t_t_x_t().

          extern char *gettxt();
          main()
          {
               printf(gettxt("UX:1", "This is an example\n"));
               printf(gettxt("UX:2", "Hello world!\n"));
          }

FFFFIIIILLLLEEEESSSS
     /usr/lib/locale/_l_o_c_a_l_e/LC_MESSAGES/*
          files created by _m_k_m_s_g_s(1)

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     User Commands (1): gettxt, mkmsgs, printf, srchtxt
     Library Functions (3): gettxt, printf, setlocale

DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     The error messages produced by _e_x_s_t_r are intended to be
     self-explanatory.  They indicate errors in the command line
     or format errors encountered within the input file.

December 1990                                 TX User's Reference