"Fossies" - the Fresh Open Source Software Archive

Member "replace-2.24/replace.1" (7 Oct 2004, 11388 Bytes) of package /linux/privat/old/replace-2.24-src-11.11.tar.gz:

Caution: As a special service "Fossies" has tried to format the requested manual source page into HTML format but links to other man pages may be missing or even erroneous. Alternatively you can here view or download the uninterpreted manual source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.




replace − Replace strings in text or binary files in a sane fashion


replace [-?] [-A] [-b] [-c startcol] [-d tmpdir] [-e] [-f] [-h] [-i] [-L] [-l linenum] [-m maxreplines] [-n] [-P] [-p] [-r|-R] [-s] [-T] [-t maxtimes] [-u backupsuffix] [-v] [-w] [-x suffix[-x...]] [-z] old_str new_str [-a old_str new_str] [filename [filename...]]


replace performs (by default) a case-insensitive search for the "word" old_str in each text line and replaces it with new_str, which is (by default) case-adjusted to match the case of the particular occurrence of old_str in the original line. A "word" is defined to be a string that is preceded AND followed by a non−alphanumeric character (start and end of lines count as such a character) in the original text line. The original versions of any modified files are (by default) saved with a ".cln" extension.

If no filenames are specified, then standard input and output are used for the replacements unless -r or -R is additionally specified (which will cause the current directory to be recursed for files instead). If "filenames" are specified with -r or -R, then they can either be files or the names of directories that will be recursed for files. If possible, modified files retain their ownership, group and permissions.


The following options are recognised:


Display a syntax usage message.


By default, replace uses the first 256 bytes of each file specified to automatically determine if the file is text or binary. By specifying this option, this auto-detection is turned off and replace assumes that all supplied files are text files. It is recommended that you avoid this option unless absolutely necessary due to the high risk of corruption of binary files that may be accidentally specified. Because of its dangerous nature, -A is now a deprecated option and may change its behaviour or be removed in a future release.

−a old_str new_str

Allows extra replacement strings to be specified in strict left-to-right order. The maximum number of replacement pairs is 255. This is equivalent to sed’s multiple -e parameters of course, so please note that the whole line is modified by the first replacement pair before it is rescanned for subsequent pairs. If -b or -h has been specified or the auto-detect code indicates the file is a binary, the binary input data is read in 16K chunks and the binary replacement pairs are applied in turn to each chunk (chunk-straddling is catered for of course).


Turns off file type auto-detection and forces replace to assume that all supplied files are binary files (i.e. the inverse of the -A option). The replacement string (new_str) must be less than or equal in length to the original string (old_str) and will not be zero-terminated unless -z is also supplied or padded with spaces unless -P or -p is used. Note that all binary replacements do not check if old_str is a "word" i.e. the -s option is enabled. Neither old_str nor new_str can be zero length (i.e. "") when -b is used.

Note that -b turns on initial checks about the suitability of the old and new strings for use in binary replacements (namely that old_str must not be zero length and new_str must be less than or equal to the length of old_str). Without the -b (or -h) option, such unsuitable strings are allowed, but will be silently ignored if the auto-detect code finds a binary file and attempts string replacements on it.
−c startcol

Starts the string replacement from column ’linenum’ onwards rather than the first column onwards. Ignored if -b or -h is also specified or if the auto-detect code indicates the file is a binary.

−d tempdir

Specifies the temporary directory used for storing modified files. If the parameter is not supplied, then the environmental variable TMPDIR is read and used instead. If TMPDIR is also not set, then /tmp will be used.


Make the search case-sensitive. new_str exactly replaces old_str with no case−adjustment to new_str.


Forces the update of files without any backup (which typically has a .cln suffix).


The original and replacement strings are normally ASCII strings, but -h switches their format to be hex strings of binary data. It also activates case-sensitive binary replacement mode (i.e. it switches on the -b and -e options). If you wanted, for example, to replace all occurrences of the byte 0 with the byte 255 instead, you’d specify "-h 0 ff".


When specified once, the user will be interactively prompted whether they want the next file to have all of the appropriate strings replaced. When specified twice ("-i -i"), the prompting switches to asking about every single string replacement in each file (the appropriate unmodified line is displayed to aid the user). As a safety precaution, verbose mode is also switched on when -i is specified (to the level of the number of -i’s stated). Note that the input is read from /dev/tty to avoid clashing with standard input and any prompts are, of course, sent to standard error.


Follows any soft-link specified on the command line to its linked-to destination before performing any replacements. If a soft-link eventually points to a directory and the -r or -R option has been specified, then that directory will be recursed (but any soft-links inside that directory will not be followed to avoid jumping out of the directory tree). If -L isn’t supplied, soft-links specified on the command line will be skipped.

−l linenum

Starts the string replacement from line ’linenum’ onwards rather than the first line onwards. Ignored if -b or -h is also specified or if the file is auto-detected as a binary.

−m maxreplines

Specifies the maximum number of lines that should have their strings replaced in a file. The default value is infinity. Ignored if -b or -h is also specified or if the file is auto-detected as a binary.


Displays what strings would be replaced without actually replacing them. It also, by necessity, switches on summary verbose mode (specify -nn to switch on all replacements verbose mode).


Pre-pads new_str with leading spaces if it is shorter than old_str.


Pads new_str with trailing spaces if it is shorter than old_str.

−r or −R

Recurses the filesystem from the current directory downwards (if no "filenames" are specified), replacing strings in every file found. Soft-links within the directory tree are ignored to avoid the recursion jumping out of that tree. The recursion can look for particular file suffixes only by the use of one or more -x parameters. If "filenames" are specified along with -r or -R, then they can either be files or the names of directories to recurse down for files. Note that files ending in the backup suffix (typically .cln) will be skipped during the recursion.


Relaxes the condition that old_str has to match a "word" i.e. it replaces old_str even if it is a substring of a "word" or if it contains only non-alphanumeric characters.


Modified files retain the timestamps of the original unmodified files if this option is specified. By default, modified files have their timestamp set to the time the file was modified (i.e. now).

−t maxtimes

States the maximum number of times a string can be replaced in any single line of a file. The default value is infinity. If -b or -h is also specified or the file is auto-detected as a binary, the maxtimes value applies to the whole binary input file.

−u backupsuffix

Changes the backup suffix of the unmodified file from the default of .cln to the specified backupsuffix value.


Increments (switches on) verbose mode. If specified once, only a brief per-file summary is reported to stderr of the files that had replacements performed on them. If specified twice (i.e. -vv), all individual replacements are additionally reported to stderr and an overall summary is also displayed. If -v isn’t specified at all (and -i or -n aren’t used), then only warnings and errors are displayed to stderr (in other words, replace operates silently by default if there are no problems).


Recursively replaces strings in all Web-related source files in the current directory tree. Equivalent to "-r -x .html -x .htm -x .asp -x .js -x .css -x .xml -x .xhtml -x .shtml -x .jsp -x .php -x .php3 -x .php4 -x .pl".

−x suffix

Specifies the suffix of the files to be case-insensitively matched when -r is used. Multiple -x parameters can be utilised with the appropriate "or" meaning as you’d expect. The maximum number of -x parameters is 255.


Zero-terminate any binary replacement string (new_str) specified, which is useful if you are replacing a zero-terminated string (e.g. a pathname) with a smaller string in an executable. If this option is used, -b must also be supplied (note that using -h or -p will cause -z to be ignored) and also new_str must be shorter than old_str in order to cater for the zero terminator.


If replace has no non-fatal errors, it will return 0, otherwise it returns 1. Fatal errors can include bad command line options or parameters, failure to allocate memory for replacement buffers, failure to read from the terminal when expecting user input and exiting replace via the "q" option when being prompted for input during "replace -i".


To make an executable use /usr/lib/libc.1 instead of /usr/lib/libc.2 (note that this is "risky" and may lead to run-time problems for the executable, but it’s one way to try to run an HP-UX 11.00 binary on HP-UX 10.20 !):

replace -bv /usr/lib/libc.2 /usr/lib/libc.1 filename

To make a file one long line (i.e. replace all line feeds with spaces):

replace -h a 20 filename

To recursively add the attribute bgcolor="#ffffff" to all <body> tags (regardless of case) in all Web-related source documents in the current directory tree downwards (but retaining the original case of the <body> tag):

replace -fswv "<body" "<body bgcolor=\"#ffffff\""


If the old or new string or the filenames you are specifying contain a space or any special shell character (e.g. brackets, pipe, backquote and so on), use single or double quotes to surround the whole string. If you want to remove a string from a file, specify "" as the new string to replace the old one. If the old or new string begins with a minus ("-"), you will have to stop command line argument parsing with -- (e.g. replace -sev -- -old new...).


Replacing strings in binary executables, object files or libraries can lead to permanent corruption of said files if you perform the replacements in a haphazard manner. You are strongly advised to keep a backup copy of any such binary files you intend to replace strings in.

Do not use the -A option (which is now officially deprecated) unless you are completely convinced that all files specified are text files. You risk severe corruption of any binaries specified otherwise.




Richard K. Lloyd <replace@richardlloyd.org.uk>