replace(1) replace(1)
NAME
replace - Replace strings in text or binary files in a sane fashion
SYNOPSIS
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...]]
DESCRIPTION
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.
OPTIONS
The following options are recognised:
-? Display a syntax usage message.
-A 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
- 1 - Formatted: May 7, 2024
replace(1) replace(1)
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).
-b 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.
-e Make the search case-sensitive. new_str exactly replaces
old_str with no case-adjustment to new_str.
-f Forces the update of files without any backup (which
typically has a .cln suffix).
-h 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".
-i When specified once, the user will be interactively prompted
whether they want the next file to have all of the
- 2 - Formatted: May 7, 2024
replace(1) replace(1)
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.
-L 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.
-n 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).
-P Pre-pads new_str with leading spaces if it is shorter than
old_str.
-p 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.
- 3 - Formatted: May 7, 2024
replace(1) replace(1)
-s 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.
-T 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.
-v 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).
-w 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.
-z 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.
RETURN VALUE
If replace has no non-fatal errors, it will return 0, otherwise it
- 4 - Formatted: May 7, 2024
replace(1) replace(1)
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".
EXAMPLES
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\""
TIPS
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...).
WARNINGS
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.
SEE ALSO BUT I WOULDN'T BOTHER
sed(1)
AUTHOR
Richard K. Lloyd <replace@richardlloyd.org.uk>
- 5 - Formatted: May 7, 2024
