trace




SYNOPSIS

     trace [-help] [-o fname] [-l len] [-p psp] [-abcefinrstvwxy]
     [ command options ... ]


DESCRIPTION

     Trace is a system utility that produces a listing of the
     MS-DOS requests made by a process.  It is a useful debugging
     tool that can be used on any executable program.  Trace can
     also be used to provide a better understanding of the inter-
     nal workings of many programs.  A utility with the same name
     and similar functionality is provided with SunOS.

     Trace can monitor either a command passed as an argument,
     all the resident processes in the system or a process with a
     given program segment prefix (PSP).  In all cases it creates
     a file (trace.log by default) where each system call and its
     arguments made by the process(es) monitored are printed.  A
     number of options control the detail of information printed.


OPTIONS

     -a   Monitor all system calls.  By default the following
          functions are traced: disp_out (0x02), direct_out
          (0x06), disp_string (0x09), flush (0x0d),
          set_current_disk (0x0e), get_current_disk (0x19),
          set_dta (0x1a), drive_info (0x1c), set_vector (0x25),
          parse_name (0x29), get_date (0x2a), get_time (0x2c),
          set_time (0x2d), get_dta (0x2f), get_version (0x30),
          cntrl_brk (0x33), get_flag (0x34), get_vector (0x35),
          mkdir (0x39), rmdir (0x3a), chdir (0x3b), creat (0x3c),
          open (0x3d), close (0x3e), read (0x3f), write (0x40),
          unlink (0x41), lseek (0x42), chmod (0x43), ioctl
          (0x44), dup (0x45), dup2 (0x46), getcwd (0x47), alloc
          (0x48), free (0x49), realloc (0x4a), exec (0x4b), exit
          (0x4c), get_code (0x4d), findfirst (0x4e), findnext
          (0x4f), set_psp (0x50), get_psp (0x51), sysvars (0x52),
          child_psp (0x55), get/set_time (0x57),
          get/set_alloc_str (0x58), tmpfile (0x5a).  create_new
          (0x5b).  get_psp (0x62), open (0x6c), Functions not
          included in the above list are printed by default using
          their function number without their arguments.

     -b   Print the interrupt branch address.  Each line is pre-
          ceded by the address on which the MS-DOS interrupt was
          generated.

     -c   Only a summary count of all calls is produced at the
          end of the program run.  No detailed information is
          given.  One line is produced for each function used.
          The line contains the function number in hexadecimal,
          the symbolic function name and the number of times the
          function was called.


     -f   Calls are prefixed with the MS-DOS function call
          number.

     -h   A short help list on the program options is displayed
          on the standard output.

     -i   Calls are prefixed with the process-id of the process
          that performed them.  This is the PSP address of the
          program under MS-DOS.

     -l L Specify the number of bytes printed for input / output
          calls.  Up to L bytes of data will be printed.  The
          default number is 15.

     -n   Functions that are not normally printed are printed by
          a short descriptive name rather than their function
          number.

     -o F The output file for tracing information is F instead of
          the default trace.log.  Note that F can also be a dev-
          ice name such as con or prn.

     -p P Trace a process with process-id (PSP address) P.  This
          is usually a terminate and stay resident (TSR) utility.
          To obtain the PSP address of the program use a memory
          display utility such as dosmem or mi or run trace with
          the -i option.

     -r   Produce a register dump on functions that do not have
          their arguments printed.

     -s   Print strings on various functions.  The functions
          affected are:

          + For all input/output functions follow the function
            call with the string that was read or written.  The
            maximum length of the string is specified with the -l
            option.  The string is followed by an ellipsis (...)
            if it contains more characters than the maximum
            length.  The default length is 15 characters.  Non
            ASCII data is not printed unless the -x option is
            given.

          + The ioctl calls that get the device mode have it
            printed as symbolic constants.

          + The get and set filemode functions have the file mode
            printed as a string similar to that produced by the
            Unix ls -l command.

          + The directory name returned by the get current
            functions are printed together with their associated
            information.

     -t   Prefix all system calls with time in the form of
          hh:mm:ss.

     -v   Verbose option.  This option will produce the highest
          amount of data. It is equivalent to specifying the
          -aefinrstwx options.  A trace line printed using these
          options will resemble the following:
          22:11:56 2c40 40 2C50:4B26 write(1, 3200:923E, 1) =
          1  "r"
          The contents of the line are: the time, PSP address of
          the calling process, function call number, address that
          generated the function call, the function, its argu-
          ments, the return value and the string written.

     -w   Errors from MS-DOS functions are printed in word form
          (i.e. symbolically) rather than as error codes.

     -x   Data printed under the -s option will be printed even
          if it is not ASCII in hexadecimal form.

     -y   Close log file after every write.  Useful for debugging
          programs that crash.


SEE ALSO

     D. Spinellis.  Trace: A tool for logging operating system
     call transactions.  Operating Systems Review, 28(4):56-63,
     October 1994.
     Ralf Brown and Jim Kyle.  The PC Interrupt List.  Addison-
     Wesley, 1991.


AUTHOR

     (C) Copyright 1991, 1994 Diomidis Spinellis.  All rights
     reserved.
     e-mail: dspin@leon.nrcps.ariadne-t.gr
     snail mail: SENA S.A., Kyprou 27, GR-152 37 Filothei,
     Greece.


BUGS

     Most FCB calls and a number of ioctl requests are not
     decoded.

     There should be an option to merge consequentive write(2)
     requests.

     The system call used by trace to get the exit code of the
     process run is also traced.


Man(1) output converted with man2html