home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / Borland / Cplus45 / BC45 / DOC.PAK / UTILS.TXT < prev   
Text File  |  1995-08-29  |  46KB  |  1,241 lines
  1.                         UTILS.TXT
  2.                         =========
  3. Borland C++ comes with many stand-alone utilities. This file
  4. documents the following tools and utilities:
  5.  
  6. -----------------------------------------------------
  7. Name         Description
  8. -----------------------------------------------------
  9. Documented in this file:
  10.  
  11. BGIOBJ       Borland Graphics Interface
  12. CPP CPP32    Stand-alone preprocessors
  13. MIDL         Microsoft RPC compiler
  14. GREP         File-search utility
  15. OBJXREF      Object module cross-referencer
  16. TRIGRAPH     Character-conversion utility
  17. -------------------------------------------------------
  18.  
  19. ============================================================
  20. BGIOBJ: CONVERTING GRAPHICS DRIVERS AND FONTS
  21. ============================================================
  22. BGIOBJ.EXE converts graphics driver files and
  23. character sets (stroked font files) to object (.OBJ)
  24. files. Once files are converted, you can link them into
  25. your program, making them part of the executable file.
  26.  
  27. Linking drivers and fonts directly into your program is
  28. advantageous because the executable file contains all
  29. (or most) of the drivers and/or fonts it might need,
  30. and doesn't need to access the driver and font files on
  31. disk when running. However, linking the drivers and fonts
  32. into your executable file increases the EXE file size.
  33.  
  34. The BGIOBJ.EXE simplified syntax is:
  35.  
  36.    BGIOBJ source_file
  37.  
  38. where source_file is the driver or font file to be converted
  39. to an object file. The new object file created has the same
  40. file name as the source file, with the extension .OBJ.
  41.  
  42. Adding the new .OBJ files to GRAPHICS.LIB
  43. -----------------------------------------
  44. You should add the driver and font object modules to
  45. GRAPHICS.LIB, so the linker can locate them when it
  46. links in the graphics routines. If you don't add these
  47. new object modules to GRAPHICS.LIB, you'll have to add
  48. them to the list of files in the project (.IDE) file,
  49. on the BCC command line, or on the TLINK command line.
  50. To add these object modules to GRAPHICS.LIB, invoke
  51. TLIB with the following command line:
  52.  
  53.   tlib graphics + object_file_name [+ object_file_name]
  54.  
  55. where object_file_name is the name of the OBJ file created
  56. by BGIOBJ.EXE. The .OBJ extension is implied, so you don't
  57. need to include it. You can add several files with one
  58. command line to save time.
  59.  
  60. Registering the drivers and fonts
  61. ---------------------------------
  62. After adding driver and font object modules to
  63. GRAPHICS.LIB, you have to register all the drivers and
  64. fonts that you want linked in; you do this by calling
  65. registerbgidriver and registerbgifont in your program
  66. (before calling initgraph). This informs the graphics
  67. system of the presence of those files, and ensures that they
  68. are linked when the linker creates the executable file.
  69.  
  70. The registering routines each take one parameter; a
  71. symbolic name defined in graphics.h. Each registering
  72. routine returns a nonnegative value if the driver or
  73. font is registered successfully.
  74.  
  75. The following table lists drivers and fonts in Borland C++
  76. that you use with registerbgidriver and registerbgifont.
  77.  
  78. ------------------------------------------------------------
  79. Driver file  registerbgidriver  Font file  registerbgifont
  80. (*.BGI)      symbolic name      (*.CHR)    symbolic name
  81. ------------------------------------------------------------
  82. CGA          CGA_driver         TRIP       triplex_font
  83. EGAVGA       EGAVGA_driver      LITT       small_font
  84. HERC         Herc_driver        SANS       sansserif_font
  85. ATT          ATT_driver         GOTH       gothic_font
  86. PC3270       PC3270_driver
  87. IBM8514      IBM8514_driver
  88. ------------------------------------------------------------
  89.  
  90. BGIOBJ Example
  91. --------------
  92. Suppose you want to convert the files for the CGA
  93. graphics driver, the gothic font, and the triplex font
  94. to object modules, then link them into your program.
  95. Here's what you do:
  96.  
  97. 1. Convert the three binary files to object files using
  98.    BGIOBJ.EXE (creates files CGA.OBJ, TRIP.OBJ, GOTH.OBJ).
  99.  
  100. 2. You can add these object files to GRAPHICS.LIB with
  101.    this TLIB command line:
  102.  
  103.    tlib  graphics  +cga  +trip  +goth
  104.  
  105. 3. If you don't add the object files to GRAPHICS.LIB,
  106.    you must add the object file names CGA.OBJ,
  107.    TRIP.OBJ, and GOTH.OBJ to your project list (if you
  108.    are using Borland C++'s integrated environment), or
  109.    to the BCC command line. For example, the BCC command
  110.    line would look like this:
  111.  
  112.     BCC  niftgraf graphics.lib cga.obj trip.obj goth.obj
  113.  
  114. 4. Register these files in your graphics program:
  115.  
  116.    /* Header file declares CGA_driver, triplex_font &
  117.       gothic_font */
  118.    #include <graphics.h>
  119.    /* Register and check for errors */
  120.    if (registerbgidriver(CGA_driver) < 0) exit(1);
  121.    if (registerbgifont(triplex_font) < 0) exit(1);
  122.    if (registerbgifont(gothic_font)  < 0) exit(1);
  123.  
  124.     /* ... */
  125.  
  126.     initgraph(....);/* initgraph should be called
  127.    after registering */
  128.  
  129.     /* ... */
  130.  
  131. The /F option
  132. -------------
  133. This section explains what steps to take if you get the
  134. linker error Segment exceeds 64K (or a similar error)
  135. after linking in several driver and/or font files
  136. (especially with small- and compact-model programs).
  137.  
  138. By default, the files created by BGIOBJ.EXE all use the
  139. same segment (called _TEXT). This can cause problems if
  140. your program links in many drivers and/or fonts, or
  141. when you're using the small or compact memory model.
  142.  
  143. To solve this problem, you can convert one or more of
  144. the drivers or fonts with the BGIOBJ /F option. This
  145. option directs BGIOBJ to use a segment name of the form
  146. filename_TEXT, so that the default segment is not
  147. overburdened by all the linked-in drivers and fonts
  148. (and, in small and compact model programs, all the program
  149. code). For example, the following two BGIOBJ command lines
  150. direct BGIOBJ to use segment names of the
  151. form EGAVGA_TEXT and SANS_TEXT.
  152.  
  153.  bgiobj  /F  egavga
  154.  bgiobj  /F  sans
  155.  
  156. When you select /F, BGIOBJ also appends F to the target
  157. object file name (EGAVGAF.OBJ, SANSF.OBJ, and so
  158. forth), and appends _far to the name that will be used
  159. with registerfarbgidriver and registerfarbgifont. (For
  160. example, EGAVGA_driver becomes EGAVGA_driver_far.)
  161.  
  162. For files created with /F, you must use these far
  163. registering routines instead of the regular
  164. registerbgidriver and registerbgifont. For example,
  165.  
  166.  if (registerfarbgidriver(EGAVGA_driver_far) < 0)
  167.  exit(1);
  168.  if (registerfarbgifont(sansserif_font_far)  < 0)
  169.  exit(1);
  170.  
  171. Advanced features
  172. -----------------
  173. This section explains some of BGIOBJ's advanced
  174. features, and the routines registerfarbgidriver and
  175. registerfarbgifont.
  176.  
  177. This is the full syntax of the BGIOBJ.EXE command line:
  178.  
  179. BGIOBJ /F source destination public-name seg-name seg-class
  180.  
  181. This table describes components of the BGIOBJ command line.
  182. ------------------------------------------------------------
  183. Component    Description
  184. ------------------------------------------------------------
  185. /F or -F     Instructs BGIOBJ.EXE to use a segment name
  186.              other than _TEXT (the default), and to change
  187.              the public name and destination file name.
  188.  
  189. source       This is the driver or font file to be converted.
  190.              If the file is not one of the driver/font files
  191.              shipped with Borland C++, you should specify a 
  192.              full file name (including extension).
  193.  
  194. destination  Names the object file produced. The default
  195.              destination file name is source.OBJ (sourceF.OBJ
  196.              if you use the /F option).
  197.  
  198. public-name  This is the name used in the program in a call to
  199.              registerbgidriver or registerbgifont (or their
  200.              respective far versions) to link in the object
  201.              module. The public name is the external name used
  202.              by the linker, so it should be the name used in
  203.              the program, prefixed with an underscore. If your
  204.              program uses Pascal calling conventions, use
  205.              uppercase letters and don't add an underscore.
  206.  
  207. seg-name     This is an optional segment name; the default is
  208.              _TEXT (or filename_TEXT if /F is specified)
  209.  
  210. seg-class    An optional segment class; the default is CODE.
  211. ------------------------------------------------------------
  212. All parameters except source are optional. However, if
  213. you need to specify an optional parameter, all the
  214. parameters preceding it must also be specified.
  215.  
  216. If you choose to use your own public name(s), you have
  217. to add declaration(s) to your program, using one of the
  218. following forms:
  219.  
  220.  void public_name(void);   /* if /F not used, */
  221.   /* default segment name
  222.  used */
  223.  
  224.  extern int far public_name[];  /* if /F used, or */
  225.   /* segment name not
  226.  _TEXT */
  227.  
  228. In these declarations, public_name matches the public-
  229. name you used when converting with BGIOBJ. The
  230. graphics.h header file contains declarations of the
  231. default driver and font public names; if you use those
  232. default public names you don't have to declare them as
  233. just described.
  234.  
  235. After these declarations, you have to register all the
  236. drivers and fonts in your program. If you don't use the
  237. /F option and don't change the default segment name,
  238. you should register drivers and fonts through
  239. registerbgidriver and registerbgifont; otherwise, use
  240. registerfarbgidriver and registerfarbgifont.
  241.  
  242. Here is an example of a program that loads a font file
  243. into memory:
  244.  
  245.     /* Example of loading a font file into memory */
  246.  
  247.     #include <graphics.h>
  248.     #include <io.h>
  249.     #include <fcntl.h>
  250.     #include <stdio.h>
  251.     #include <conio.h>
  252.     #include <stdlib.h>
  253.     #include <process.h>
  254.     #include <alloc.h>
  255.  
  256.     main()
  257.     {
  258.      void  *gothic_fontp; /* points to font buffer in memory */
  259.      int handle;          /* file handle used for I/O */
  260.        unsigned fsize;    /* size of file (and buffer) */
  261.  
  262.        int errorcode;
  263.        int graphdriver;
  264.        int graphmode;
  265.  
  266.     /* open font file */
  267.        handle = open("GOTH.CHR", O_RDONLY|O_BINARY);
  268.        if (handle == -1)
  269.        {
  270.      printf("unable to open font file 'GOTH.CHR'\n");
  271.      exit(1);
  272.        }
  273.     /* find out size of the file */
  274.        fsize = filelength(handle);
  275.     /* allocate buffer */
  276.        gothic_fontp = malloc(fsize);
  277.        if (gothic_fontp == NULL)
  278.        {
  279.     printf("unable to allocate memory for font file
  280.     'GOTH.CHR'\n");
  281.     exit(1);
  282.        }
  283.     /* read font into memory */
  284.        if (read(handle, gothic_fontp, fsize) != fsize)
  285.        {
  286.      printf("unable to read font file 'GOTH.CHR'\n");
  287.      exit(1);
  288.        }
  289.     /* close font file */
  290.        close(handle);
  291.     /* register font */
  292.        if (registerfarbgifont(gothic_fontp) !=
  293.     GOTHIC_FONT)
  294.        {
  295.      printf("unable to register font file
  296.     'GOTH.CHR'\n");
  297.      exit(1);
  298.        }
  299.     /* detect and initialize graphix */
  300.        graphdriver = DETECT;
  301.        initgraph(&graphdriver, &graphmode, "..");
  302.        errorcode = graphresult();
  303.        if (errorcode != grOk)
  304.        {
  305.      printf("graphics error:
  306.     %s\n",grapherrormsg(errorcode));
  307.      exit(1);
  308.        }
  309.  
  310.        settextjustify(CENTER_TEXT, CENTER_TEXT);
  311.        settextstyle(GOTHIC_FONT, HORIZ_DIR, 4);
  312.        outtextxy(getmaxx()/2,getmaxy()/2,
  313.        "Borland Graphics Interface (BGI)");
  314.     /* press a key to terminate */
  315.        getch();
  316.     /* shut down graphics system */
  317.        closegraph();
  318.        return(0);
  319.     }
  320.  
  321. ============================================================
  322. CPP and CPP32: THE PREPROCESSORS
  323. ============================================================
  324. CPP and CPP32 produce a list (in a file) of a C program in
  325. which include files and #define macros have been expanded.
  326. Unless otherwise noted, CPP refers to both CPP and CPP32.
  327. Neither is needed for normal compilation of C programs.
  328.  
  329. Often, when the compiler reports an error inside a macro or
  330. an include file, you can get more information about what the
  331. error is if you can see the include files or the results of
  332. the macro expansions. In many multi-pass compilers, a
  333. separate pass performs this work, and the results of the
  334. pass can be examined. Because Borland C++ uses an integrated
  335. single-pass compiler, use CPP to get the first-pass 
  336. functionality found in other compilers.
  337.  
  338. CPP works similarly to BCC: it reads the same TURBOC.CFG
  339. file for default options and uses the same command-line
  340. options as BCC. CPP ignores any BCC options that don't
  341. pertain to CPP, and there is no special treatment for .OBJ,
  342. .LIB, or .ASM files. CPP32 uses the same command-line
  343. options that BCC32 uses.
  344.  
  345. For each file processed by CPP, the output is written
  346. to a file in the current directory (or the output
  347. directory named by the -n option) with the same name as
  348. the source name but with an extension of .I.
  349.  
  350. This output file is a text file containing each line of the
  351. source file and any include files. Any preprocessing 
  352. directive lines have been removed, along with any conditional
  353. text lines excluded from the compile. Unless you use a 
  354. command-line option to specify otherwise, text lines are
  355. prefixed with the file name and line number of the source or
  356. include file the line came from. Within a text line, any
  357. macros are replaced with their expansion text.
  358.  
  359. IMPORTANT!  The resulting output of CPP cannot be compiled
  360. because of the file name and line number prefix attached to
  361. each source line.
  362.  
  363. CPP as a macro preprocessor
  364. ---------------------------
  365. The -P option tells CPP to prefix each line with the source
  366. file name and line number. With the -P- option, CPP can be
  367. used as a macro preprocessor; the resulting .I file can then
  368. be compiled with BCC or BCC32. (Note that you can also use the
  369. BCC option -P to set default file extensions.)
  370.  
  371. The following simple program illustrates how CPP
  372. preprocesses a file, first with -P selected, then with -P-.
  373.  
  374.      Source file: HELLOAJ.C
  375.       #define NAME "H.R. Floyd"
  376.       #define BEGIN {
  377.       #define END   }
  378.  
  379.       main()
  380.       BEGIN
  381.          printf("%s\n", NAME);
  382.       END
  383.  
  384. CPP command line:   CPP HELLOAJ.C
  385. Output:
  386.     HELLOAJ.c 1:
  387.     HELLOAJ.c 2:
  388.     HELLOAJ.c 3:
  389.     HELLOAJ.c 4:
  390.     HELLOAJ.c 5: main()
  391.     HELLOAJ.c 6: {
  392.     HELLOAJ.c 7:    printf("%s\n","H.R. Floyd");
  393.     HELLOAJ.c 8: }
  394.  
  395. CPP command line:   CPP -P- HELLOAJ.C
  396. Output:
  397.     main()
  398.     {
  399.        printf("%s\n","H.R. Floyd");
  400.     }
  401.  
  402. Using MIDL with CPP.EXE and CPP32.EXE
  403. -------------------------------------
  404. MIDL (Microsoft Interface Definition Language) is an RPC
  405. compiler. In order to use MIDL, with Borland C++'s
  406. preprocessors, you must use the following MIDL command:
  407.  
  408. MIDL -cpp_cmd {CPP|CPP32} -cpp_opt "-P- -oCON {CPP options}"
  409.      {MIDL options} {.idl/.acf}
  410.  
  411. -cpp_cmd {CPP|CPP32}   Tells MIDL which preprocessor to use
  412.                        when processing an .IDL or .ACF file.
  413.                        MIDL calls the preprocessor to expand
  414.                        macros within source files.
  415.  
  416. -cpp_opt "{options}"   Specifies the preprocessor's command-
  417.                        line options. The -P- removes line
  418.                        number and file name information from
  419.                        each line of the preprocessed output.
  420.                        The -oCON indicates that preprocessed
  421.                        output should go to standard output,
  422.                        instead of to file. The preprocessor's
  423.                        banner and the current file that is
  424.                        being processed are not emitted.
  425.                        Including -oCON within a .CFG file
  426.                        processed by the preprocessor causes
  427.                        the banner to be emitted.
  428.                        {CPP options} pass options to CPP.
  429.  
  430. {MIDL options}         Any MIDL command-line options.
  431.  
  432. {.idl/.acf file}       The source file that MIDL processes.
  433.  
  434.  
  435. CPP and UUIDs
  436. -------------
  437. In some cases, CPP doesn't accept valid UUIDs. For example,
  438. a valid UUID statement is:
  439.    uuid(5630EAA0-CA48-1067-B320-00DD010662DB)
  440.  
  441. When CPP or CPP32 encounter 5630EAA0, it is classified as a
  442. floating point number, and since it's an invalid floating
  443. point number, the preprocessor emits an error. To work
  444. around this problem, enclose the UUID within quotes and use
  445. the -ms_ext MIDL option. The UUID statement becomes:
  446.    uuid("5630EAA0-CA48-1067-B320-00DD010662DB")
  447.  
  448. and the MIDL command line becomes:
  449.   MIDL -ms_ext -cpp_cmd {CPP|CPP32} -cpp_opt "-P- -oCON
  450.        {CPP options}" {MIDL options} {.idl/.acf file}
  451.  
  452.  
  453. =============================================================
  454. GREP: A TEXT-SEARCH UTILITY
  455. =============================================================
  456. GREP (Global Regular Expression Print) is a powerful
  457. text-search program derived from the UNIX utility of
  458. the same name. GREP searches for a text pattern in one
  459. or more files or in its standard input stream.
  460.  
  461. Here's a quick example of a situation where you might
  462. want to use GREP. Suppose you wanted to find out which
  463. text files in your current directory contained the
  464. string "Bob". You would type:
  465.  
  466.     grep Bob *.txt
  467.  
  468. GREP responds with a list of the lines in each file (if any)
  469. that contained the string "Bob". Because GREP ignores case by
  470. default, the strings "bob" and "boB" also match.
  471.  
  472. GREP can do a lot more than match a single, fixed string.
  473. In the following section, you'll see how to make GREP search
  474. for any string that matches a particular pattern.
  475.  
  476. Command-line syntax
  477. -------------------
  478. The general command-line syntax for GREP is
  479.  
  480.   grep [options] searchstring [file(s) ... ]
  481.  
  482. options      consist of one or more letters, preceded by a
  483.              hyphen (-), that change GREP's behavior.
  484. searchstring gives the pattern to search for.
  485. file(s)      tells GREP which files to search. (If you don't
  486.              specify a file, GREP searches standard input;
  487.              this lets you use pipes and redirection.) If you
  488.              find that the results of your GREP are longer
  489.              than one screen, you can redirect the output to
  490.              a file. For example, you could use this command
  491.                GREP "Bob" *.txt > temp.txt
  492.              which searches all files with the TXT extension
  493.              in the current directory, then puts the results
  494.              in a file called TEMP.TXT. (You can name this
  495.              file anything you like.) Use any word processor
  496.              to read TEMP.TXT (the results of the search).
  497.  
  498. The command GREP ? prints a help screen showing GREP's
  499. options, special characters, and defaults.
  500.  
  501. GREP options
  502. ------------
  503. In the command line, options are one or more single
  504. characters preceded by a hyphen (-). Each individual
  505. character is a switch that you can turn on or off: A
  506. plus symbol (+) after a character turns the option on;
  507. a hyphen (-) after the character turns the option off.
  508. The + sign is optional; for example, -r means the same
  509. thing as -r+. You can list multiple options
  510. individually (like this: -i -d -l), or you can combine
  511. them (like this: -ild or -il, -d, and so on).
  512.  
  513. Here are the GREP option characters and their meanings:
  514. ------------------------------------------------------------
  515. Option  Meaning
  516. ------------------------------------------------------------
  517.   -c    Match Count only: Prints only a count of matching
  518.         lines. For each file that contains at least one
  519.         matching line, GREP prints the file name and a
  520.         count of the number of matching lines. Matching lines
  521.         are not printed. This option is off by default.
  522.  
  523.   -d    Search subdirectories: For each file specified on the
  524.         command line, GREP searches for all files that match
  525.         the file specification, both in the directory
  526.         specified and in all subdirectories below the specified
  527.         directory. If you give a file without a path, GREP
  528.         assumes the files are in the current directory. This
  529.         option is off by default.
  530.  
  531.   -i   Ignore case: GREP ignores upper/lowercase differences.
  532.        When this option is on, GREP treats all letters a to z
  533.        as identical to the corresponding letters A to Z in all
  534.        situations. This option is on by default.
  535.  
  536.   -l   List file names only: Prints only the name of each file
  537.        containing a match. After GREP finds a match, it prints
  538.        the file name and processing immediately moves on to the
  539.        next file. This option is off by default.
  540.  
  541.   -n   Line Numbers: Each matching line that GREP prints is
  542.        preceded by its line number. This option is off by default.
  543.  
  544.   -o   UNIX output format: Changes the output format of
  545.        matching lines to support more easily the UNIX style
  546.        of command-line piping. All lines of output are
  547.        preceded by the name of the file that contained the 
  548.        matching line. This option is off by default.
  549.  
  550.   -r   Regular expression search: The text defined by
  551.        searchstring is treated as a regular expression
  552.        instead of as a literal string. This option is on by
  553.        default. A regular expression is one or more occurrences
  554.        of one or more characters optionally enclosed in quotes.
  555.        The following symbols are treated specially:
  556.              ^  start of line        $  end of line
  557.              .  any character        \  quote next character
  558.              *  match zero or more   +  match one or more
  559.        [aeiou0-9]   match a, e, i, o, u, and 0-9
  560.        [^aeiou0-9]  match all but a, e, i, o, u, and 0-9
  561.  
  562.   -u   Update options: GREP adds any options from the command
  563.        line to its default options in GREP.COM. This option
  564.        lets you to customize the default option settings.
  565.        To see the defaults are set in GREP.COM, type GREP ?,
  566.        then each option on the help screen is followed by a +
  567.        or a - depending on its default setting.
  568.  
  569.   -v   Nonmatch: Prints only nonmatching lines. Only lines
  570.        that don't contain the search string are considered
  571.        nonmatching lines. This option is off by default.
  572.  
  573.   -w   Word search: Text found that matches the regular
  574.        expression is considered a match only if the character
  575.        immediately preceding and following cannot be part of
  576.        a word. The default word character set includes A to Z,
  577.        0 to 9, and the underscore ( _ ). This option is off
  578.        by default. An alternate form of this option lets you
  579.        specify the set of legal word characters. Its form is
  580.        -w[set], where set is any valid regular expression.
  581.  
  582.        If you define the set with alphabetic characters, it
  583.        is automatically defined to contain both the uppercase
  584.        and lowercase values for each letter in the set
  585.        (regardless of how it is typed), even if the search is
  586.        case-sensitive. If you use the -w option in combination
  587.        with the -u option, the new set of legal characters
  588.        is saved as the default set.
  589.  
  590.   -z   Verbose: GREP prints the file name of every file
  591.        searched. Each matching line is preceded by its
  592.        line number. A count of matching lines in each file
  593.        is given, even if the count is zero. This option is
  594.        off by default.
  595. ------------------------------------------------------------
  596.  
  597. The search string
  598. -----------------
  599. The value of searchstring defines the pattern GREP searches
  600. for. A search string can be either a regular expression or
  601. a literal string.
  602.  
  603. o In a regular expression, certain characters have special
  604.   meanings: They are operators that govern the search.
  605.  
  606. o In a literal string, there are no operators: Each
  607.   character is treated literally.
  608.  
  609. You can enclose the search string in quotation marks to
  610. prevent spaces and tabs from being treated as delimiters.
  611. The text matched by the search string cannot cross line
  612. boundaries; that is, all the text necessary to match the
  613. pattern must be on a single line.
  614.  
  615. A regular expression is either a single character or a set
  616. of characters enclosed in brackets. A concatenation of
  617. regular expressions is a regular expression.
  618.  
  619. When you use the -r option (on by default), the search
  620. string is treated as a regular expression (not a literal
  621. expression. The following characters have special meanings:
  622. ------------------------------------------------------------
  623. Option   Meaning
  624. ------------------------------------------------------------
  625.  
  626.   ^      A circumflex at the start of the expression matches
  627.          the start of a line.
  628.  
  629.   $      A dollar sign at the end of the expression matches
  630.          the end of a line.
  631.  
  632.   .      A period matches any character.
  633.  
  634.   *      An expression followed by an asterisk matches
  635.          zero or more occurrences of that expression. For
  636.          example, in to*, the * operates on the expression o;
  637.          it matches t, to, too, etc. (t followed by zero or
  638.          more os), but doesn't match ta.
  639.  
  640.   +      An expression followed by a plus sign matches one
  641.          or more occurrences of that expression: to+ matches
  642.          to, too, etc., but not t.
  643.  
  644.   [ ]    A string enclosed in brackets matches any character
  645.          in that string. If the first character in the string
  646.          is a circumflex (^), the expression matches any
  647.          character except the characters in the string.
  648.          For example, [xyz] matches x, y, or z, while [^xyz]
  649.          matches a and b, but not x, y, or z. You can specify
  650.          a range of characters with two characters separated
  651.          by a hyphen (-). These can be combined to form
  652.          expressions (like [a-bd-z?], which matches the ?
  653.          character and any lowercase letter except c).
  654.  
  655.   \      The backslash escape character tells GREP to search
  656.          for the literal character that follows it. For
  657.          example, \. matches a period instead of "any
  658.          character." The backslash can be used to quote
  659.          itself; that is, you can use \\ to indicate a literal
  660.          backslash character in a GREP expression.
  661. ------------------------------------------------------------
  662.  
  663. Four of the "special" characters ($, ., *, and +) don't
  664. have any special meaning when used within a bracketed
  665. set. In addition, the character ^ is only treated
  666. specially if it immediately follows the beginning of
  667. the set definition (immediately after the [ delimiter).
  668.  
  669. File specifications
  670. -------------------
  671. The files option tells GREP which files to search. Files
  672. can be an explicit file name or a generic file name 
  673. incorporating the DOS ? and * wildcards. In addition, you
  674. can type a path (drive and directory information). If you
  675. list files without a path, GREP searches the current directory.
  676. If you don't specify any files, input to GREP must come
  677. from redirection (<) or a vertical bar (|).
  678.  
  679. Some GREP examples
  680. ------------------
  681. The following examples show how to combine GREP's
  682. features to do different kinds of searches. They assume
  683. GREP's default settings are unchanged.
  684.  
  685. EXAMPLE 1       grep -r [^a-z]main\ *( *.c
  686. matches:                           Does not match:
  687.   main(i,j:integer)                  mymain()
  688.   if (main  ()) halt;
  689.   if (MAIN  ()) halt;
  690.  
  691. The search string tells GREP to search for the word main
  692. with no preceding lowercase letters ([^a-z]), followed by
  693. zero or more occurrences of blank spaces (\ *), then a 
  694. left parenthesis. Since spaces and tabs are normally 
  695. considered command-line delimiters, you must quote them if
  696. you want to include them as part of a regular expression.
  697. In this case, the space after main is quoted with the
  698. backslash escape character. You could also accomplish
  699. this by placing the space in double quotes.
  700.  
  701.  
  702. EXAMPLE 2       grep -ri [a-c]:\\data\.fil *.c *.inc
  703. Matches:    A:\data.fil            Does not match:
  704.   c:\Data.Fil                        d:\data.fil
  705.   B:\DATA.FIL                        a:data.fil
  706.  
  707. Because the backslash (\) and period (.) characters
  708. usually have special meaning in path and file names,
  709. you must place the backslash escape character 
  710. immediately in front of them if you want to search for them.
  711. The -i option is used here, so the search is not case
  712. sensitive.
  713.  
  714.  
  715. EXAMPLE 3         grep "search string with spaces" *.doc *.c
  716. Matches:          This is a search string with spaces in it.
  717. Does not match:         This search string has spaces in it.
  718.  
  719. This is an example of how to search for a string with
  720. embedded spaces.
  721.  
  722.  
  723. EXAMPLE 4         grep -rd "[ ,.:?'\"]"$ \*.doc
  724. Matches:    He said hi to me.
  725.   Where are you going?
  726.   In anticipation of a unique situation,
  727.   Examples include the following:
  728.   "Many men smoke, but fu man chu."
  729.  
  730. Does not match:
  731.   He said "Hi" to me
  732.   Where are you going? I'm headed to the
  733.  
  734. This example searches for any one of the characters
  735. " . : ? ' and , at the end of a line. The double quote
  736. within the range is preceded by an escape character so it is
  737. treated as a normal character instead of as the ending quote
  738. for the string. Also, the $ character appears outside of the
  739. quoted string. This demonstrates how regular expressions can
  740. be concatenated to form a longer expression.
  741.  
  742.  
  743. EXAMPLE 5         grep -w[=] = *.c
  744. Matches:    i = 5;             Does not match:
  745.   j=5;                          if (i == t) j++;
  746.   i += j;                       /* =================== */
  747.  
  748. This example redefines the current set of legal
  749. characters for a word as the assignment operator (=)
  750. only, then does a word search. It matches C assignment
  751. statements, which use a single equal sign (=), but not
  752. equality tests, which use a double equal sign (==).
  753.  
  754.  
  755. ============================================================
  756. OBJXREF: THE OBJECT MODULE CROSS-REFERENCE UTILITY
  757. ============================================================
  758. OBJXREF examines a list of object files and library
  759. files and produces reports on their contents. One type
  760. of report lists definitions of public names and
  761. references to them. The other type lists the segment
  762. sizes defined by object modules.
  763.  
  764. There are two categories of public names: global
  765. variables and function names. The TEST1.C and TEST2.C
  766. files in the section "Sample OBJXREF reports" (page 25)
  767. illustrate definitions of public names and external
  768. references to them.
  769.  
  770. Object modules are object (.OBJ) files produced by BC, BCC
  771. or TASM. A library (.LIB) file contains multiple object
  772. modules. An object module generated by BC is given the same
  773. name as the .C source file it was compiled from. This is
  774. also true for BCC, unless a different output file name is
  775. specifically indicated with the -o BCC command-line option.
  776.  
  777. The OBJXREF command line
  778. ------------------------
  779. The OBJXREF command line consists of the word OBJXREF
  780. followed by a series of command-line options and a list
  781. of object and library file names, separated by a space
  782. or tab character. The syntax is as follows:
  783.  
  784.   OBJXREF @responsefile  options   filename  filename ...
  785.  
  786. The command-line options determine the kind of reports that
  787. OBJXREF generates and the amount of detail that OBJXREF
  788. provides. Each option begins with a forward slash (/)
  789. followed by a one- or two-character option name.
  790. Options are discussed in detail in the next section.
  791.  
  792. Object files and library files may be specified either on
  793. the command line or in a response file. On the command line,
  794. file names are separated by a space or a tab. All object
  795. modules specified as .OBJ files are included in reports.
  796. Like TLINK, however, OBJXREF includes only those modules from
  797. .LIB files which contain a public name referenced by an .OBJ
  798. file or by a previously included module from a .LIB file.
  799.  
  800. As a general rule, you should list all the .OBJ and .LIB
  801. files that are needed if the program is to link correctly,
  802. including the startup .OBJ file and one or more C libraries.
  803.  
  804. File names may include a drive and directory path. The
  805. DOS ? and * wildcard characters may be used to identify
  806. more than one file. File names may refer to .OBJ object
  807. files or to .LIB library files. (If you don't give a
  808. file extension, the .OBJ extension is assumed.)
  809.  
  810. Options and file names may occur in any order in the
  811. command line.
  812.  
  813. OBJXREF reports are written to the DOS standard output.
  814. The default is the screen. The reports can be sent to a
  815. printer (as with >LPT1:) or to a file (as with
  816. >lstfile) with the DOS redirection character (>).
  817.  
  818. Entering OBJXREF with no file names or options produces
  819. a summary of available options.
  820.  
  821. OBJXREF command-line options fall into two categories:
  822. control options and report options.
  823.  
  824. Control options
  825. ---------------
  826. Control options modify the default behavior of OBJXREF
  827. (the default is that none of these options are
  828. enabled).
  829. -------------------------------------------------------
  830. Option   Meaning
  831. -------------------------------------------------------
  832.   /I     Ignore case differences in public names. Use
  833.          this option if you use TLINK without the /C
  834.          option (which makes case differences
  835.          significant).
  836.  
  837.   /D     Look for .OBJ files in another directory. If you
  838.          want OBJXREF to look for .OBJ files in a
  839.          directory other than the current one, include
  840.          the directory name on the command line, prefixed
  841.          with /D:
  842.                OBJXREF /Ddir1 [; dir2 [; dir3]]
  843.                      or
  844.                OBJXREF /Ddir1 [/Ddir2] [/Ddir3]
  845.          OBJXREF searches each of the directories in the
  846.          specified order for all object and library files.
  847.  
  848.          Important!    If you don't use a /D option, OBJXREF
  849.          searches only the current directory. If you do use
  850.          a /D option, however, the current directory isn't
  851.          searched unless it is included in the directory
  852.          list.
  853.  
  854.   /F     Include full library. All object modules in
  855.          specified .LIB files are included even if they
  856.          do not contain public names that are referenced
  857.          by an object module being processed by OBJXREF.
  858.          This provides information on the entire contents
  859.          of a library file. (See example 4 in the section
  860.          "OBJXREF examples.")
  861.  
  862.   /O     Lets you to specify an output file where OBJXREF
  863.          sends any generated reports. Its syntax is:
  864.          OBJXREF file.obj /report option /Ooutputfilename.ext
  865.          By default all output is sent to the screen.
  866.  
  867.   /V     Verbose output. Lists names of files read and displays
  868.          totals of public names, modules, segments, and classes.
  869.  
  870.   /Z     Include zero-length segment definitions. Object
  871.          modules may define a segment without allocating any
  872.          space in it. Listing these zero length segment
  873.          definitions normally makes the module size reports
  874.          harder to use but it can be valuable if you are
  875.          trying to remove all definitions of a segment.
  876.  
  877. Report options
  878. --------------
  879. Report options govern what sort of report is generated,
  880. and the amount of detail that OBJXREF provides.
  881. -------------------------------------------------------
  882. Option   Report generated
  883. --------------------------------------------------
  884.   /RC    Report by class type: Module sizes ordered
  885.          by class type of segment.
  886.  
  887.   /RM    Report by module: Public names ordered by
  888.          defining module.
  889.  
  890.   /RP    Report by public names: Public names in
  891.          order with defining module name.
  892.  
  893.   /RR    Report by reference: Public name definitions
  894.          and references ordered by name.
  895.  
  896.   /RS    Report of module sizes: Module sizes ordered
  897.          by segment name.
  898.  
  899.   /RU    Report of unreferenced symbol names:
  900.          Unreferenced public names ordered by defining module.
  901.  
  902.   /RV    Verbose reporting: produces a report of every type.
  903.  
  904.   /RX    Report by external reference: External
  905.          references ordered by referencing module name.
  906. --------------------------------------------------
  907.  
  908. Public names defined in .C files appear in reports with
  909. a leading underscore in the reports unless the -U-
  910. option was specified when the file was compiled (main
  911. appears as _main).
  912.  
  913. You can limit the modules, segments, classes, or public
  914. names that OBJXREF reports on by entering the
  915. appropriate name on the command line prefixed with the
  916. /N option. For example,
  917.  
  918.    OBJXREF filelist /RM /NC0
  919.  
  920. tells OBJXREF to generate a report listing information
  921. only for the module named C0.
  922.  
  923.  
  924.  
  925. Sample OBJXREF reports
  926. ----------------------
  927. Suppose you have two source files in your Borland C++
  928. directory, and want to generate OBJXREF reports on the
  929. object files compiled from them. The source files are
  930. called TEST1.C and TEST2.C, and they look like this:
  931.  
  932.     /* test1.c */
  933.     int i1;   /* defines i1 */
  934.     extern int i2; /* refers to i2 */
  935.     static int i3; /* not a public name */
  936.     extern void look(void);  /* refers to look */
  937.  
  938.     void main(void)/* defines main */
  939.     {
  940.        int i4;/* not a public name */
  941.  
  942.        look();/* refers to look */
  943.     }
  944.  
  945.     /* test2.c */
  946.     #include <process.h>
  947.     extern int i1; /* refers to i1 */
  948.     int i2;   /* defines i2 */
  949.  
  950.     void look(void)/* defines look */
  951.     {
  952.        exit(i1);   /* refers to exit... */
  953.     }    /* and to i1 */
  954.  
  955. The object modules compiled from these source files are
  956. TEST1.OBJ and TEST2.OBJ. You can tell OBJXREF what kind
  957. of report to generate about these .OBJ files by
  958. entering the file names on the command line, followed
  959. by a /R and a second letter denoting report type.
  960.  
  961.   Note  The following examples show only useful parts of the
  962. output.
  963.  
  964.  
  965. Report by public names (/RP)
  966. ----------------------------
  967. A report by public names lists each of the public names
  968. defined in the object modules being reported on,
  969. followed by the name of the module in which it is defined.
  970.  
  971. If you enter this on the command line:
  972.  
  973.     OBJXREF  /RP  test1  test2
  974.  
  975. OBJXREF generates a report that looks like this:
  976.  
  977.     SYMBOL DEFINED IN
  978.     _i1    TEST1
  979.     _i2    TEST2
  980.     _look  TEST2
  981.     _main  TEST1
  982.  
  983.  
  984. Report by module (/RM)
  985. ----------------------
  986. A report by module lists each object module being
  987. reported on, followed by a list of the public names
  988. defined in it.
  989.  
  990. If you enter this on the command line:
  991.  
  992.    OBJXREF  /RM  test1  test2
  993.  
  994. OBJXREF generates a report that looks like this:
  995.  
  996.     MODULE: TEST1 defines the following symbols:
  997.         _i1
  998.         _main
  999.     MODULE: TEST2 defines the following symbols:
  1000.         _i2
  1001.         _look
  1002.  
  1003.  
  1004. Report by reference (/RR)
  1005. -------------------------
  1006. A report by reference lists each public name with 
  1007. the defining module in parentheses on the same line.
  1008. Modules that refer to this public name are listed on
  1009. following lines indented from the left margin.
  1010.  
  1011. If you enter this on the command line:
  1012.  
  1013.   OBJXREF  /RR  C0S  test1  test2  CS.LIB
  1014.  
  1015. OBJXREF generates a report that looks like this:
  1016.  
  1017.     _exit (EXIT)
  1018.     C0
  1019.     TEST2
  1020.     _i1 (TEST1)
  1021.     TEST2
  1022.     _look (TEST2)
  1023.     TEST1
  1024.     _main (TEST1)
  1025.     C0
  1026.  
  1027.  
  1028. Report by external references (/RX)
  1029. -----------------------------------
  1030. A report by external references lists each module followed
  1031. by a list of external references it contains.
  1032.  
  1033. If you enter this on the command line:
  1034.  
  1035.    OBJXREF  /RX  C0S  test1  test2  CS.LIB
  1036.  
  1037. OBJXREF generates a report that looks like this:
  1038.  
  1039.     MODULE: C0 references the following symbols:
  1040.        _main
  1041.     MODULE: TEST1 references the following symbols:
  1042.        _i2
  1043.        _look
  1044.     MODULE: TEST2 references the following symbols:
  1045.        _exit
  1046.        _i1
  1047.  
  1048.  
  1049. Report of module sizes (/RS)
  1050. ----------------------------
  1051. A report by sizes lists segment names followed by a
  1052. list of modules that define the segment. Sizes in bytes
  1053. are given in decimal and hexadecimal notation. The word
  1054. uninitialized appears where no initial values are
  1055. assigned to any of the symbols defined in the segment.
  1056. Segments defined at absolute addresses in a .ASM file
  1057. are flagged Abs to the left of the segment size.
  1058.  
  1059. If you enter this on the command line:
  1060.  
  1061.    OBJXREF  /RS  test1  test2
  1062.  
  1063. OBJXREF generates a report that looks like this:
  1064.  
  1065. TEST1_TEXT, PUBLIC
  1066.             10 (0000Ah)    TEST1
  1067.             10 (0000Ah)    total
  1068.  
  1069. TEST2_TEXT, PUBLIC
  1070.             15 (0000Fh)    TEST2
  1071.             15 (0000Fh)    total
  1072.  
  1073. _BSS, PUBLIC
  1074.              4 (00004h)    TEST1, uninitialized
  1075.              2 (00002h)    TEST2, uninitialized
  1076.              6 (00006h)    total
  1077.  
  1078.  
  1079. Report by class type (/RC)
  1080. --------------------------
  1081. A report by class type lists segment size definitions
  1082. by segment class. The CODE class contains instructions,
  1083. DATA class contains initialized data and BSS class
  1084. contains uninitialized data. Segments which do not have
  1085. a class type are listed under the notation No class type.
  1086.  
  1087. If you enter this on the command line:
  1088.  
  1089.    OBJXREF  /RC  C0S  test1  test2  CS.LIB
  1090.  
  1091. OBJXREF generates a report that looks like this:
  1092.  
  1093. BSS
  1094.              4 (00004h)    _BSS, TEST1, uninitialized
  1095.              2 (00002h)    _BSS, TEST2, uninitialized
  1096.              6 (00006h)    total
  1097.  
  1098. CODE
  1099.              8 (00008h)    _TEXT, TEST1
  1100.             13 (0000Dh)    _TEXT, TEST2
  1101.             21 (00015h)    total
  1102.  
  1103.  
  1104. Report of unreferenced symbol names (/RU)
  1105. -----------------------------------------
  1106. A report of unreferenced symbol names lists modules that
  1107. define public names not referenced in other modules. Such
  1108. a symbol is either:
  1109.  
  1110.   o referenced only from within the defining module and
  1111.     does not need to be defined as a public symbol (in
  1112.     that case, if the module is in C, the keyword static
  1113.     should be added to the definition; if the module is
  1114.     in TASM, just remove the public definition).
  1115.  
  1116.   o never used (therefore, it can be deleted to save code
  1117.     or data space).
  1118.  
  1119. If you enter this on the command line:
  1120.  
  1121.    OBJXREF  /RU  test1  test2
  1122.  
  1123. OBJXREF generates a report that looks like this:
  1124.  
  1125.    MODULE: TEST2 defines the unreferenced symbol _i2.
  1126.  
  1127.  
  1128. Verbose reporting (/RV)
  1129. -----------------------
  1130. If you enter /RV on the command line, OBJXREF generates
  1131. one report of each type.
  1132.  
  1133.  
  1134. OBJXREF Examples
  1135. ----------------
  1136. These examples assume that the application files are in
  1137. the current directory of the default drive and that the
  1138. Borland C++ startup files (C0x.OBJ) and the library
  1139. files are in the \BC45\LIB directory.
  1140.  
  1141.  
  1142. EXAMPLE 1  C>OBJXREF \BC45\lib\c0l test1 test2 \BC45\lib\cl.lib
  1143.  
  1144. In this example, the TEST1.OBJ and TEST2.OBJ files and the
  1145. Borland C++ startup file \BC45\LIB\C0L.OBJ and the library
  1146. file \BC45\LIB\CL.LIB are specified. Since no report type is
  1147. specified, the resulting report is the default report by
  1148. reference, listing public names and the modules that
  1149. reference them.
  1150.  
  1151.  
  1152. EXAMPLE 2         C>OBJXREF /RV /Ltest1.arf
  1153.  
  1154. The TLINK response file TEST1.ARF contains the same
  1155. list of files as the command line in Example 1. The /RV
  1156. option is specified, so a report of every type is
  1157. generated. TEST1.ARF contains
  1158.      \BC45\lib\c0l
  1159.      test1 test2
  1160.      test1.exe
  1161.      test1.map
  1162.      \BC45\lib\cl
  1163.  
  1164.  
  1165. EXAMPLE 3       C>OBJXREF /F /RV \BC45\lib\cs.lib
  1166.  
  1167. This example reports on all the modules in the Borland
  1168. C++ library file CS.LIB; OBJXREF can produce useful
  1169. reports even when the files specified do not make a
  1170. complete program. The /F causes all modules in CS.LIB
  1171. file to be included in the report.
  1172.  
  1173.  
  1174. OBJXREF error messages and warnings
  1175. -----------------------------------
  1176. OBJXREF generates two types of diagnostic messages:
  1177. error messages and warnings.
  1178.  
  1179. Out of memory error
  1180. OBJXREF performs its cross referencing in RAM memory and
  1181. might run out of memory even if TLINK is able to link the
  1182. same list of files successfully. When this happens, OBJXREF
  1183. stops. Remove memory resident programs to get more space,
  1184. or add more RAM.
  1185.  
  1186. WARNING: Unable to open input file <filename>
  1187. The input file filename could not be located or opened.
  1188. OBJXREF proceeds to the next file.
  1189.  
  1190. WARNING: Unknown option - <option>
  1191. The option name option is not recognized by OBJXREF.
  1192. OBJXREF ignores the option.
  1193.  
  1194. WARNING: Unresolved symbol <symbol> in module <module>
  1195. The public name symbol referenced in module module is
  1196. not defined in any of the .OBJ or .LIB files specified.
  1197. OBJXREF flags the symbol in any reports it generates as
  1198. being referenced but not defined.
  1199.  
  1200. WARNING: Invalid file specification <filename>
  1201. Some part of the file name filename is invalid. OBJXREF
  1202. proceeds to the next file.
  1203.  
  1204. WARNING: No files matching <filename>
  1205. The file named filename listed on the command line or
  1206. in a response file could not be located or opened.
  1207. OBJXREF skips to the next file.
  1208.  
  1209. WARNING: Symbol <symbol> defined in <module1>
  1210. duplicated in <module2>
  1211. Public name symbol is defined in modules module1 and
  1212. module2. OBJXREF ignores the second definition.
  1213.  
  1214.  
  1215. ============================================================
  1216. TRIGRAPH: A character-conversion utility
  1217. ============================================================
  1218. Trigraphs are three-character sequences that replace
  1219. certain characters used in the C language that are not
  1220. available on some keyboards. Translating trigraphs in
  1221. the compiler would slow compilation down considerably,
  1222. so Borland C++ provides a filter named TRIGRAPH.EXE to
  1223. handle trigraph sequences when you need to. The syntax
  1224. for invoking this program is as follows:
  1225.  
  1226. TRIGRAPH [-u] file(s) [file(s) ...]
  1227.  
  1228. The following table shows the trigraph sequences that
  1229. TRIGRAPH.EXE recognizes:
  1230.  
  1231.  Trigraph  Characters
  1232. -------------------------------------------------------
  1233.  
  1234.     ??=   #    ??(   [
  1235.     ??/   \    ??)   ]
  1236.     ??'   ^    ??<   {
  1237.     ??!   |    ??>   }
  1238.     ??-   ~
  1239.  
  1240. =================END OF FILE UTILS.TXT======================
  1241.