          gsar(1)                                                   gsar(1)


          NAME
                 gsar - General Search And Replace utility


          SYNOPSIS
                 gsar [options] [infile(s)] [outfile]


          DESCRIPTION
                 gsar (General Search And Replace) is a utility for search-
                 ing for and --- optionally --- replacing strings  in  both
                 text  and binary files. The search and replace strings can
                 contain all kinds of characters (0--255), i.e. Ctrl  char-
                 acters and extended ASCII as well.

                 The  algorithm  used  is  a  variation  of the Boyer-Moore
                 search algorithm, modified to search binary  files.  As  a
                 result of this, gsar is blindingly fast.

                 Opposed  to  line oriented search programs (like grep(1)),
                 gsar will find all  matches  on  a  line.  Actually,  gsar
                 doesn't  know  anything  about lines at all, all files and
                 strings are treated as binary.

                 Gsar can search one or several  files  for  a  string  and
                 report the occurrences. Gsar can read one file, search for
                 a string, replace it with some other string, and create  a
                 new file containing the changes. Gsar can perform a search
                 and replace in multiple files, overwriting the  originals.
                 Finally,  gsar can work as a filter, reading from standard
                 input and writing to standard output.


          OPTIONS
                 All options can be concatenated into one single option i.e
                 the command: gsar  -i -b -l is the same as gsar -ibl

                 An  option which takes an argument must be the last one in
                 the concatenated option, since the rest of the  option  is
                 taken as a possible argument.

                 Fields  enclosed  in  []  are optional, but mandatory when
                 enclosed in <>.  Options are case sensitive i.e -b is  not
                 the same as -B.

                 If no options are given, gsar just gives a brief help mes-
                 sage.

             [infile(s)]
                 Name(s) of input file(s) (wildcards allowed on  most  Unix
                 shells  and  most DOS compilers). If the -F option is used
                 input is taken from stdin.

             [outfile]
                 Name of output file that is to contain  the  replacements.
                 If  the  -F  option is used, transformed output is sent to
                 stdout.

             -s<string>
                 String to search for  in  file.  Ctrl  characters  can  be
                 entered by using a `:' in the string followed by the ASCII
                 value of the character. The value is entered using  a  `:'
                 followed  by  three decimal digits or `:x' followed by two
                 hex numbers.  To enter a colon (:) in the  search  pattern
                 use `::'.  The string must follow directly after s.

                 Example:  To  search for the string :foo (`o' is 111 deci-
                 mal, 6F in hex) use the search options:
                   -s::foo or -s::fo:111 or -s::fo:x6F

                 If you want to search for a  string  with  spaces  in  it,
                 under  MSDOS  surround  the expression with quotes.  Under
                 Unix, use the mechanisms  your  shell  provides  (commonly
                 quotes) to include space or other special characters.

                 Example: search for gsar is fast use:
                   gsar "-sgsar is fast" foobar.txt

                 The  precompiled  MSDOS executable in the archive supports
                 response files. Just put you gsar commands into a file and
                 put  a  `@'  in  front of the filename on the gsar command
                 line.

                 Example: file foobar.txt contains  -ssupercalifragilistic-
                 expialidocus:
                   gsar @foobar.txt poppins.txt

                 If response files are needed, most Unix shells will allow
                   gsar `cat foobar.txt` poppins.txt

             -r[string]
                 String  which  is to replace search string in file. Use -r
                 to delete the search string from  the  file  i.e.  replace
                 with  nothing.  Ctrl characters can be entered in the same
                 way as in the search string. If this option is  left  out,
                 gsar  only  performs  a  search.  The  string  must follow
                 directly after r.

             -i
                 Ignore case difference when comparing strings.  I.e.  foo-
                 bar matches fooBAR.

             -B
                 Just  display  the search & replace buffers, for test pur-
                 poses.

             -f
                 If the output file already exists this switch can be  used
                 to force an overwrite of the existing output file.

             -o
                 Search  and replace of multiple files, overwrite the input
                 file(s). For each input  file,  gsar  creates  a  tempfile
                 which contains the replacements and copies the tempfile to
                 the original input file name. If no  matches  were  found,
                 the input file stays the same. The tempfile is removed.

                 Example:
                   gsar -s__ZTC__ -r__TURBOC__ -o foo.c bar.c bat.c
                 The files foo.c, bar.c & bat.c are all changed.

             -c[n]
                 Display  the  context  around a match in a textual manner.
                 Undisplayable characters are displayed as a dot  (`.').  n
                 is  optional  number  of  bytes  in context. n must follow
                 directly after c.

             -x[n]
                 Display the context around a match as a hexadecimal  dump.
                 Undisplayable  characters  are displayed as a dot (`.'). n
                 is optional number of bytes  in  context.  n  must  follow
                 directly after x.

             -b
                 Display the byte offset of the match in hex.

             -l
                 Only list filename and number of matches if any (default).

             -h
                 Suppress display of filename when  displaying  context  or
                 byte offsets.

             -du
                 Convert a DOS ASCII file to UNIX (strips carriage return).

             -ud
                 Convert a UNIX ASCII file to DOS (adds carriage return).

             -F
                 Filter mode, gsar takes it's input from  stdin  and  redi-
                 rects  eventual  output  to stdout. All error messages are
                 sent stderr.

             -G
                 Display the GNU General Public Licence.


          Examples
                 Search for two spaces at the end of a line (DOS text)  and
                 replace with just a carriage return overwriting the origi-
                 nal files:

                   gsar  -s:x20:x20:x0d  -r:x0d  -o  foobar.txt  *.c

                 Convert a UNIX text file to  DOS  format  overwriting  the
                 original file:

                   gsar  -ud  -o  unix.txt

                 Search  for  the  string  WATCOM  and replace with __ZTC__
                 using gsar as a filter. Output  is  redirected  to  a  new
                 file:

                   gsar  -sWATCOM  -r__ZTC__  -F  <  foo_w.c  >  foo_z.c

                 Display  textual  context  of the string error in the file
                 gsar.exe disregarding case. With 40 bytes in the context:

                   gsar  -serror  -i  -c40  gsar.exe

                 Search for the string gnu in the file fsf and  replace  it
                 with wildebeest, creating a new output file africa:

                   gsar  -sgnu  -rwildebeest  fsf  africa

                 (if  the file africa exists, you have to use the -f option
                 to overwrite it.)

                 Search for the string error in the  file  command.com  and
                 display the byte offset of each match:

                   gsar  -serror  -b  command.com


          Limitations
                 No  wildcards  or  regular  expressions  allowed in search
                 string.

                 On MSDOS platforms stdin from a tty is not allowed because
                 stdin  has  been  turned into binary. MSDOS will not catch
                 the Ctrl-Z signifying EOF.

          Authors
                 Tormod Tjaberg (coding, design (all bugs are his))
                 Hans Peter Verne (ideas, demands, testing, UNIX platforms)

                 If  you have any comments, bug reports or whatever, we can
                 be reached through email at:

                 tormod@sn.no
                 hpv@kjemi.uio.no
