SYNOPSIS

cstrings [-c] [-r ranges] [-t template] [-m minlength] files…​

DESCRIPTION

This tool can be used to massage input C source so that literal strings in it are replaced by generated #define symbols, with the list of #defines prepended to the resulting source code. String literals on #include and #define lines and in comments are skipped.

If no filenames are given, standard input is filtered to standard output. If filenames are given (and appropriate write permissions are present), each file is replaced by its converted result (the replace is done with a link(2), so the program is signal-safe). To avoid heartbreak and death threats to the author, it is recommended that you not use this feature without looking at the filtered version first to ensure that it’s what you really want.

The string argument of a -r option is interpreted as a comma-separated list of line numbers or line number ranges to which the string filtering is to be limited. A range of the form "<num1>-" is taken to signify all lines from line <num1> to EOF; a range of the form "-<num2>" signifies all lines from the start of file to line <num2>. Additionally, any range or number may be preceded by '!'; this causes filtering to be suppressed for the lines designated. If the first character of a range option is '!', filtering is assumed initially on for all lines, rather than off.

The -t option sets the template with which string labels are generated. The default is "G%05d". The template is sprintf’ed with a sequence number as argument.

The -m option takes a numeric argument, interpreted as a minimum length. All strings less than that size are ignored. Note that this minimum length defaults to 3, you must say <option>-m</option> 1 or <option>-m</option> 2 to see all short strings.

The -c option suppresses the normal action and instead causes a list of strings that would otherwise be #define-ized (each preceded by its line number) to be emitted to stdout. If <option>-c</option> is used with file arguments a report with sections headed by file names will be generated.

The -c option permits you to anticipate the effects of a substitution without having to look at the whole source file.

This tool is best used by doing repeated <option>-c</option> runs, adding to an -r argument until you have it down to filtering just the lines you want, and then dropping the -c to do the actual conversion. Then you can move the list of generated #defines to an appropriate spot with a text editor.

BUGS

This program makes no effort to be intelligent about duplicate strings. Also, it doesn’t handle quoted quotes within strings.

AUTHOR

Eric S. Raymond <esr@snark.thyrsus.com>. See my WWW home page at http://www.tuxedo.org/~esr for updates and other resources.