This is the 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.

Overview
********

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

cdecl
cundecl
     The cdecl and cundecl utilities can be used to decode or encode a complex type declaration like

          void (*signal(int sig, void (*func)(int)))(int);

     or

          declare funcvec as array[16] of pointer to function that expects
          (void) returning int;

cobfusc
     The cobfusc utility can be used to obfuscate (i.e. render unreadable but perfectly compilable) some code. For 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");
          }

     can be converted to:

          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");}

chilight
     The 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).

cunloop
     The cunloop does a job like the cobfusc utility: it obfuscates the source code, by unlooping the C language loop and branch instructions while, do, for, if into a sequence of goto instuctions to render the source file unreadable. While cobfusc works with every C source code, cunloop is semantically-dependant.

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

yyref
     The yyref utility is a Yacc cross-reference generator.

cdecl and cundecl
*****************

The cdecl and cundecl utilities can be used to decode or encode a complex type declaration like

     void (*signal(int sig, void (*func)(int)))(int);

or

     declare funcvec as array[16] of pointer to function that expects
     (void) returning int;

Invoking cdecl
==============

The options are as follows:

-o file
     Set the output destination to file.

-V
     Print version information on standard output then exit.

Invoking cundecl
================

The options are as follows:

-o file
     Set the output destination to file.

-V
     Print version information on standard output then exit.

cdecl and cundecl examples
==========================

cdecl input examples:

     char *s;
     void (*signal(int sig, void (*func)(int)))(int);
     (const char *)s;
     (void (*)(int))signal_function;
     char (*func[64])(int a, char *p);

cundecl input examples:

     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;

cobfusc
*******

From the 13th International Obfuscated C Code Contest (Check out the IOCCC Web page:	http://www.ioccc.org) Rules:

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.

The 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.

Invoking cobfusc
================

The options are as follows:

-A
     Enable a heavy obfuscation for the source file. This is equivalent to the -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.

-a
     Garble every string with octal escapes.

-b
     Enable the digraphize mode.

-c no | lower | upper | screw | random
     Set the identifier case obfuscation mode.

-d
     Compact the macros removing backslashes and white-spaces when they are not required.

-e
     Compact the white-spaces when they are not required.

-f suffix
     Put the output of each processed file in a separate file with suffix appended to file name instead of standard output.  This is useful when processing a lot of source files.

     For example, cobfusc -f .obf.c foo.c bar.c will create two files, foo.c.obf.c and bar.c.obf.c.

-g file
     Add first the identifiers contained in file to the obfuscation table.

     Useful when those identifiers are shared between two or more source files.

-i numeric | word | random
     Set the identifier obfuscation mode.

-m
     Strip the comments.

-n
     Garble integers with expressions.

-o file
     Set the output destination to file.

-p prefix
     Specify the prefix to use when generating the identifiers.

-r file
     Tell cobfusc that the identifiers contained in file must not be obfuscated.

-s seed
     Specify the seed for generating the random numbers.

-t
     Enable the trigraphize mode.

-u
     Dump the symbol table to file. This option is useful for debugging.

-V
     Print version information on standard output then exit.

-w cols
     Set the width limit of the output.

-x
     Exclusive mode; obfuscate only the identifiers specified by the -g and -z parameters.

-z file
     Add the identifiers pairs contained in 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:

          find_file ff1
          find_buffer ff2
          close_buffer ff3
          save_buffer ff4

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.

??(
     is replaced by [

??)
     is replaced by ]

??<
     is replaced by {

??>
     is replaced by }

??/
     is replaced by \

??'
     is replaced by ^

??=
     is replaced by #

??!
     is replaced by |

??-
     is replaced by ~

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.

<:
     is replaced by [

:>
     is replaced by ]

<%
     is replaced by {

%>
     is replaced by }

%:
     is replaced by #

%:%:
     is replaced by ##

cobfusc examples
================

If you just want to compact the whitespaces, try:

     cobfusc -de <inputfile >outputfile

To remove the comments, try:

     cobfusc -m <inputfile >outputfile

If you want to convent all the identifiers to meaningless computer generated ones, try:

     cobfusc -inumeric <inputfile >outputfile

Or, if instead of numbers you like silly words like ``foo'' and ``bar'', try:

     cobfusc -iword <inputfile >outputfile

For a heavy obfuscation, try:

     cobfusc -A <inputfile >outputfile

Or for a maximum obfuscation, try:

     cobfusc -Abn -irandom -crandom <inputfile >outputfile

To obfuscate a program composed by two or more source files:

     cobfusc -A -f .obf.c first.c second.c third.c

chilight
********

The 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).

Invoking chilight
=================

The options are as follows:

-f format
     Set the output format to format.  The format can be one of tty (the default), ansi_color, ansi_bold, html_color, html_font or roff.

-o file
     Set the output destination to file.

-t title
     Specify the page title for the generated HTML page.

-V
     Print version information on standard output then exit.

chilight examples
=================

For highlighting a source file with ANSI color escapes, try:

     chilight -f ansi_color <inputfile

For highlighting a source file with HTML color commands, try:

     chilight -f html_color <inputfile

For highlighting a source file with HTML font commands, try:

     chilight -f html_font <inputfile

cunloop
*******

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

Invoking cunloop
================

The options are as follows:

-o file
     Set the output destination to file.

-p prefix
     Set the identifier prefix for generating the labels.

-V
     Print version information on standard output then exit.

cunloop examples
================

For unlooping a source file, try:

     cunloop <inputfile >outputfile

For unlooping a source file using foo_ as the prefix for generating the labels, try:

     cunloop -p foo_ <inputfile >outputfile

yyextract
*********

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

Invoking yyextract
==================

The options are as follows:

-b
     Select the Backus-Naur Form (BNF) for the output.

-e
     Select the Extended Backus-Naur Form (EBNF) for the output.

-h
     Output in HTML format.

-o file
     Set the output destination to file.

-t title
     Specify the page title for the generated HTML page.

-w cols
     Set the width limit of the output (this sets only the width of the %token header).

-y
     Select the yacc format for the output. This is the default format.

-V
     Print version information on standard output then exit.

yyextract examples
==================

For extracting the rules from a Yacc grammar, try:

     yyextract <inputfile >outputfile

For extracting the rules from a Yacc grammar in BNF format, try:

     yyextract -b <inputfile >outputfile

For extracting the rules from a Yacc grammar in EBNF/HTML format, try:

     yyextract -eh <inputfile >outputfile

yyref
*****

The yyref utility is a Yacc cross-reference generator.

Invoking yyref
==============

The options are as follows:

-o file
     Set the output destination to file.

-V
     Print version information on standard output then exit.

yyref examples
==============

For creating the cross-references from a Yacc grammar, try:

     yyref <inputfile

Bug reports
***********

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