QSUBST(1)

NAME
qsubst - query/substitute strings in files

SYNOPSIS
qsubst string1 string2 [ options / files ]

DESCRIPTION
Qsubst is designed for substituting strings in (large) files. It accepts a list of file names and two strings. For each of the files, qsubst modifies it in-place to replace string1 with string2 wherever the user approves the change.

Each time qsubst finds the string1 in a file, it prints a few lines of context (see the -c option below) and expects the user to type a character to indicate whether or not the replacement should be done. The user can type:

space
    Replace this instance and go on to the next one.

.   Replace this instance but don't do any more in this file (ie, go on to the next file).

n   Don't change this instance, just go on to the next one.

^G  Don't change this instance or any more in this file, just go on to the next file.

!   Change this instance and all further ones in this file without asking, then go on to the next file (for which qsubst will begin asking again).

The arguments preceding the strings are interpreted as filenames (which qsubst then performs replacements in) if they do not begin with - signs. If they do, they are interpreted as follows:

-!

-go

-noask
    Don't bother asking, just replace. This is like hitting ! as soon as the first instance appears for each file except that nothing is printed. This is in effect for all files encountered until a -nogo or -ask option is given. Note that if you use csh, you will probably have to backslash the !, which is why the alternative forms exist.

-nogo

-ask
    Negate a -go or -noask option. Qsubst will once more prompt the user as usual.

-CAN
    Give N lines of context above the line with the match when prompting the user.

-CBN
    Give N lines of context below the line with the match when prompting the user.

-cN Give N lines of context above and as many below the line with the match when prompting the user (equivalent to -CAN -CBN).

-f filename
    Same as a simple filename argument, but is useful if the file name begins with a -.

-F filename
    Qsubst reads file names from the file, one per line, and performs substitutions on the files whose names it reads thus.

ERRORS
Qsubst can generate the following error messages:

Usage: qsubst str1 str2 [ -! -noask -go -f file -F file ]

This is a usage message printed if fewer than two arguments are given.

qsubst: argument order has changed, it's now: str1 str2 files...

Qsubst used to take arguments differently; the two strings were the *last* two arguments rather than the first two. This message is printed if the first argument is a valid file name but the last two are not - qsubst assumes that you didn't know of the change yet. However, qsubst continues as though what you gave were actually what you meant.

qsubst: cannot create temp file /tmp/qsubst.012345

(The number may vary). This message is generated if qsubst cannot open its temporary file (the name appears in the message). Something is seriously wrong with either qsubst or /tmp.

qsubst: search string too long (max 512 chars)

This is surely self-explanatory.

qsubst: -C must be -CA or -CB

You gave -C, but it was neither -CA nor -CB.

qsubst: -f what?
qsubst: -F what?

You gave -f (or - without a file name.

qsubst: cannot read filename

Qsubst couldn't open the named file for read-only.

qsubst: cannot rewrite filename

Qsubst couldn't open the named file read/write for substitution.

NOTES
Qsubst reads its argument list in order and processes files as it comes to them. Hence (for instance), a -go option will affect only files named after the -go option.

The most context you can get is -c10.

The search string (string1) is limited to 512 characters. There is no similar limit on the length of the replacement string (string2).

Nulls in the file may cause qsubst to make various mistakes.

If any other program modifies the file while qsubst is running, all bets are off.

Qsubst expect the files it is performing substitutions in to be real files, that is, objects on which lseek(2) works sensibly. Not, for example, terminals or pipes.

Qsubst is careful to modify files only when necessary, so it interacts nicely with make(1).

AUTHOR
der Mouse (Mike Parker, mcgill-vision!mouse), March, 1985.