\input texinfo   @c -*-texinfo-*-
@setfilename cutils.info
@settitle The cutils Manual

@c If "finalout" is commented out, the printed output will show
@c black boxes that mark lines that are too long.  Thus, it is
@c unwise to comment it out when running a master in case there are
@c overfulls which are deemed okay.

@iftex
@c @finalout
@end iftex

@setchapternewpage odd

@titlepage
@title The cutils Manual
@subtitle Edition 1.6 for cutils version 1.6
@subtitle July 2001
@author Sandro Sigala

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1997-2001 Sandro Sigala @email{sandro@@sigala.it}.
@end titlepage

@c ---------------------------------------------------------------------------
@node Top, Overview, (dir), (dir)

This is the @emph{cutils} manual.

The cutils package is a collection of utilities for ``C''
programmers.  They are mostly parsers that convert an input file
written in a particular format into another format.

@menu
* Overview::                    An overview of the cutils package.
* cdecl/cundecl::               Decode and encode C type declarations.
* cobfusc::                     Make a C source file unreadable but compilable.
* chilight::                    Highlight C source files.
* cunloop::                     Unloop C loops.
* yyextract::                   Extract grammar rules from Yacc grammars.
* yyref::                       Yacc grammar reference program.
* Bug reports::                 How to report a bug.
@end menu

@c ---------------------------------------------------------------------------
@node Overview, cdecl/cundecl, Top, Top
@chapter Overview

The utilities enclosed in the @emph{cutils} package
are usually useful in some circumstances during the development
in the ``C'' language.

@table @emph
@item cdecl
@itemx cundecl
The @emph{cdecl} and @emph{cundecl} utilities
can be used to decode or encode a complex type declaration like
@example
void (*signal(int sig, void (*func)(int)))(int);
@end example
or
@example
declare funcvec as array[16] of pointer to function that expects
(void) returning int;
@end example
@item cobfusc
The @emph{cobfusc} utility can be used to obfuscate (i.e. render
unreadable but perfectly compilable) some code.
For example:
@example
int
main(int argc, char **argv)
@{
        int i;
        printf("program name: %s\n", argv[0]);
        printf("arguments:");
        for (i = 1; i < argc; i++)
                printf(" %s", argv[i]);
        printf("\n");
@}
@end example
can be converted to:
@example
int main(int q0,char**q1)@{int q2;printf(
"\160\162\157\147\162\141\155\40\156\141\155\145\72\40\45\163\n",
q1[0]);printf("\141\162\147\165\155\145\156\164\163\72");for(q2=1;
q2<q0;q2++)printf("\40\45\163",q1[q2]);printf("\n");@}
@end example
@item chilight
The @emph{chilight} utility can be used to highlight (i.e. fontify)
a C source file with color escapes or markups, depending of the selected
output format (tty, ANSI, HTML or roff).
@item cunloop
The @emph{cunloop} does a job like the @emph{cobfusc} utility: it obfuscates
the source code, by unlooping the C language loop and branch instructions
@code{while}, @code{do}, @code{for}, @code{if} into a sequence of @code{goto}
instuctions to render the source file unreadable.
While @emph{cobfusc} works with every C source code,
@emph{cunloop} is semantically-dependant.
@item yyextract
The @emph{yyextract} utility can be used to extract the rules from
a Yacc grammar (or produce another grammar in a different format, like HTML).
@item yyref
The @emph{yyref} utility is a Yacc cross-reference generator.
@end table

@c ---------------------------------------------------------------------------
@node cdecl/cundecl, cobfusc, Overview, Top
@chapter cdecl and cundecl

The @emph{cdecl} and @emph{cundecl} utilities
can be used to decode or encode a complex type declaration like
@example
void (*signal(int sig, void (*func)(int)))(int);
@end example
or
@example
declare funcvec as array[16] of pointer to function that expects
(void) returning int;
@end example

@menu
* Invoking cdecl::              Command line options of cdecl.
* Invoking cundecl::            Command line options of cundecl.
* cdecl/cundecl examples::      Some examples of this two utilities.
@end menu

@c ---------------------------------------------------------------------------
@node Invoking cdecl, Invoking cundecl, cdecl/cundecl, cdecl/cundecl
@section Invoking cdecl

The options are as follows:

@table @samp
@item -o file
Set the output destination to @file{file}.
@item -V
Print version information on standard output then exit.
@end table

@c ---------------------------------------------------------------------------
@node Invoking cundecl, cdecl/cundecl examples, Invoking cdecl, cdecl/cundecl
@section Invoking cundecl

The options are as follows:

@table @samp
@item -o file
Set the output destination to @file{file}.
@item -V
Print version information on standard output then exit.
@end table

@c ---------------------------------------------------------------------------
@node cdecl/cundecl examples,  , Invoking cundecl, cdecl/cundecl
@section cdecl and cundecl examples

@emph{cdecl} input examples:
@example
char *s;
void (*signal(int sig, void (*func)(int)))(int);
(const char *)s;
(void (*)(int))signal_function;
char (*func[64])(int a, char *p);
@end example

@emph{cundecl} input examples:
@example
declare s as pointer to char;
declare x as function (fmt as pointer to const char, ...) returning int;
cast s into pointer to const char;
cast f into pointer to function (int) returning void;
declare foo as pointer to pointer to function that expects
(x as pointer to function that expects (c as char) returning int)
returning void;
@end example

@c ---------------------------------------------------------------------------
@node cobfusc, chilight, cdecl/cundecl, Top
@chapter cobfusc

From the 13th International Obfuscated C Code Contest@footnote{Check out the
IOCCC Web page:	@url{http://www.ioccc.org}} Rules:

@table @emph
@item Obfuscate
tr.v.  -cated, -cating, -cates.  1. a.  To render obscure.
b.  To darken.  2. To confuse:  his emotions obfuscated his
judgment.  [LLat. obfuscare, to darken : ob(intensive) +
Lat. fuscare, to darken < fuscus, dark.] -obfuscation n.
obfuscatory adj.
@end table

The @emph{cobfusc} utility converts the input file, written in the C language,
into a human unreadable one, but compilable.  The main work is converting
every identifier into a meaningless one, removing any comment and compacting
all the white-spaces when they are not required.

@menu
* Invoking cobfusc::            Command line options of cobfusc.
* Digraphs and trigraphs::      Explain the ISO C token respellings.
* cobfusc examples::            Some examples of this utility.
@end menu

@c ---------------------------------------------------------------------------
@node Invoking cobfusc, Digraphs and trigraphs, cobfusc, cobfusc
@section Invoking cobfusc

The options are as follows:

@table @samp
@item -A
Enable a heavy obfuscation for the source file.
This is equivalent to the
@samp{-ademt -inumeric}
options.  The digraphize option is not enabled by default
since the Amendement 1 (1994) changes to ISO C are supported only by
few C compilers.
@item -a
Garble every string with octal escapes.
@item -b
Enable the digraphize mode.
@item -c no | lower | upper | screw | random
Set the identifier case obfuscation mode.
@item -d
Compact the macros removing backslashes and white-spaces when
they are not required.
@item -e
Compact the white-spaces when they are not required.
@item -f suffix
Put the output of each processed file in a separate file with
@file{suffix}
appended to file name instead of standard output.  This is useful when
processing a lot of source files.

For example, @samp{cobfusc -f .obf.c foo.c bar.c} will create two files,
@file{foo.c.obf.c} and @file{bar.c.obf.c}.
@item -g file
Add first the identifiers contained in
@file{file} to the obfuscation table.

Useful when those identifiers are shared between two or more source files.
@item -i numeric | word | random
Set the identifier obfuscation mode.
@item -m
Strip the comments.
@item -n
Garble integers with expressions.
@item -o file
Set the output destination to @file{file}.
@item -p prefix
Specify the prefix to use when generating the identifiers.
@item -r file
Tell @emph{cobfusc} that the identifiers contained in @file{file} must
not be obfuscated.
@item -s seed
Specify the seed for generating the random numbers.
@item -t
Enable the trigraphize mode.
@item -u
Dump the symbol table to @file{file}.
This option is useful for debugging.
@item -V
Print version information on standard output then exit.
@item -w cols
Set the width limit of the output.
@item -x
Exclusive mode; obfuscate only the identifiers specified by the
@samp{-g} and @samp{-z} parameters.
@item -z file
Add the identifiers pairs contained in @file{file}
to the obfuscation table.  The file format is two identifier per line, separated
by a space character, the first one is the original identifier, the second
one is the obfuscated identifier.

This option is useful when a list of obfuscated identifiers must be provided
manually.

For example, this is a valid input file:
@example
find_file ff1
find_buffer ff2
close_buffer ff3
save_buffer ff4
@end example
@end table

@c ---------------------------------------------------------------------------
@node Digraphs and trigraphs, cobfusc examples, Invoking cobfusc, cobfusc
@section Digraphs and trigraphs

The ISO C language includes a set of trigraphs so that C programs may be
written using only the ISO 646-1083 Invariant Code Set, a subset
of the ASCII code set.  The trigraphs, introduced by two consecutive
question mark characters, are listed in the table below.

@table @samp
@item ??(
is replaced by @samp{[}
@item ??)
is replaced by @samp{]}
@item ??<
is replaced by @samp{@{}
@item ??>
is replaced by @samp{@}}
@item ??/
is replaced by @samp{\}
@item ??'
is replaced by @samp{^}
@item ??=
is replaced by @samp{#}
@item ??!
is replaced by @samp{|}
@item ??-
is replaced by @samp{~}
@end table

The Amendment 1 to ISO C provides six new tokens that are convenient when
writing source programs in restricted character sets (such as the
ISO 646-1083 Invariant Code Set).  The following respellings are more
readable than the equivalent form using trigraphs, and they may be
used wherever the customary tokens are permitted.

@table @samp
@item <:
is replaced by @samp{[}
@item :>
is replaced by @samp{]}
@item <%
is replaced by @samp{@{}
@item %>
is replaced by @samp{@}}
@item %:
is replaced by @samp{#}
@item %:%:
is replaced by @samp{##}
@end table

@c ---------------------------------------------------------------------------
@node cobfusc examples,  , Digraphs and trigraphs, cobfusc
@section cobfusc examples

If you just want to compact the whitespaces, try:
@example
cobfusc -de <inputfile >outputfile
@end example

To remove the comments, try:
@example
cobfusc -m <inputfile >outputfile
@end example

If you want to convent all the identifiers to meaningless computer
generated ones, try:
@example
cobfusc -inumeric <inputfile >outputfile
@end example

Or, if instead of numbers you like silly words like ``foo'' and ``bar'',
try:
@example
cobfusc -iword <inputfile >outputfile
@end example

For a heavy obfuscation, try:
@example
cobfusc -A <inputfile >outputfile
@end example

Or for a maximum obfuscation, try:
@example
cobfusc -Abn -irandom -crandom <inputfile >outputfile
@end example

To obfuscate a program composed by two or more source files:
@example
cobfusc -A -f .obf.c first.c second.c third.c
@end example

@c ---------------------------------------------------------------------------
@node chilight, cunloop, cobfusc, Top
@chapter chilight

The @emph{chilight} utility can be used to highlight (i.e. fontify)
a C source file with color escapes or markups, depending of the selected
output format (tty, ANSI, HTML or roff).

@menu
* Invoking chilight::           Command line options of chilight.
* chilight examples::           Some examples of this utility.
@end menu

@c ---------------------------------------------------------------------------
@node Invoking chilight, chilight examples, chilight, chilight
@section Invoking chilight

The options are as follows:

@table @samp
@item -f format
Set the output format to @samp{format}.  The format can be one
of
@samp{tty} (the default), @samp{ansi_color}, @samp{ansi_bold},
@samp{html_color}, @samp{html_font} or @samp{roff}.
@item -o file
Set the output destination to @file{file}.
@item -t title
Specify the page title for the generated HTML page.
@item -V
Print version information on standard output then exit.
@end table

@c ---------------------------------------------------------------------------
@node chilight examples,  , Invoking chilight, chilight
@section chilight examples

For highlighting a source file with ANSI color escapes, try:
@example
chilight -f ansi_color <inputfile
@end example

For highlighting a source file with HTML color commands, try:
@example
chilight -f html_color <inputfile
@end example

For highlighting a source file with HTML font commands, try:
@example
chilight -f html_font <inputfile
@end example

@c ---------------------------------------------------------------------------
@node cunloop, yyextract, chilight, Top
@chapter cunloop

The @emph{cunloop} does a job like the @emph{cobfusc} utility: it obfuscates
the source code, by unlooping the C language loop and branch instructions
@code{while}, @code{do}, @code{for}, @code{if} into a sequence of @code{goto}
instuctions to render the source file unreadable.
While @emph{cobfusc} works with every C source code,
@emph{cunloop} is semantically-dependant.
@emph{cunloop} can be used conjointly with @emph{cobfusc} to produce
a @strong{very} obfuscated source file.
Please note that the output of @emph{cunloop} can be very inefficient
and/or complex to be optimized by the C compiler, because the whole
of @code{goto}s produced by the unlooping.

@menu
* Invoking cunloop::            Command line options of cunloop.
* cunloop examples::            Some examples of this utility.
@end menu

@c ---------------------------------------------------------------------------
@node Invoking cunloop, cunloop examples, cunloop, cunloop
@section Invoking cunloop

The options are as follows:

@table @samp
@item -o file
Set the output destination to @file{file}.
@item -p prefix
Set the identifier prefix for generating the labels.
@item -V
Print version information on standard output then exit.
@end table

@c ---------------------------------------------------------------------------
@node cunloop examples,  , Invoking cunloop, cunloop
@section cunloop examples

For unlooping a source file, try:
@example
cunloop <inputfile >outputfile
@end example

For unlooping a source file using @code{foo_} as the prefix for generating
the labels, try:
@example
cunloop -p foo_ <inputfile >outputfile
@end example

@c ---------------------------------------------------------------------------
@node yyextract, yyref, cunloop, Top
@chapter yyextract

The @emph{yyextract} utility can be used to extract the rules from
a Yacc grammar (or produce another grammar in a different format, like HTML).

@menu
* Invoking yyextract::          Command line options of yyextract.
* yyextract examples::          Some examples of this utility.
@end menu

@c ---------------------------------------------------------------------------
@node Invoking yyextract, yyextract examples, yyextract, yyextract
@section Invoking yyextract

The options are as follows:

@table @samp
@item -b
Select the Backus-Naur Form (BNF) for the output.
@item -e
Select the Extended Backus-Naur Form (EBNF) for the output.
@item -h
Output in HTML format.
@item -o file
Set the output destination to @file{file}.
@item -t title
Specify the page title for the generated HTML page.
@item -w cols
Set the width limit of the output (this sets only the width of the
@samp{%token} header).
@item -y
Select the yacc format for the output. This is the default format.
@item -V
Print version information on standard output then exit.
@end table

@c ---------------------------------------------------------------------------
@node yyextract examples,  , Invoking yyextract, yyextract
@section yyextract examples

For extracting the rules from a Yacc grammar, try:
@example
yyextract <inputfile >outputfile
@end example

For extracting the rules from a Yacc grammar in BNF format, try:
@example
yyextract -b <inputfile >outputfile
@end example

For extracting the rules from a Yacc grammar in EBNF/HTML format, try:
@example
yyextract -eh <inputfile >outputfile
@end example

@c ---------------------------------------------------------------------------
@node yyref, Bug reports, yyextract, Top
@chapter yyref

The @emph{yyref} utility is a Yacc cross-reference generator.

@menu
* Invoking yyref::              Command line options of yyref.
* yyref examples::              Some examples of this utility.
@end menu

@c ---------------------------------------------------------------------------
@node Invoking yyref, yyref examples, yyref, yyref
@section Invoking yyref

The options are as follows:

@table @samp
@item -o file
Set the output destination to @file{file}.
@item -V
Print version information on standard output then exit.
@end table

@c ---------------------------------------------------------------------------
@node yyref examples,  , Invoking yyref, yyref
@section yyref examples

For creating the cross-references from a Yacc grammar, try:
@example
yyref <inputfile
@end example

@c ---------------------------------------------------------------------------
@node Bug reports,  , yyref, Top
@chapter Bug reports

Any questions, comments, or bug reports should be sent to the
author at the Internet email address @email{sandro@@sigala.it}.

@contents

@bye

Local Variables:
compile-command: "texi2dvi cutils.texi"
End:
