SYNOPSIS
        #include <debug_info.h>

        mixed debug_info(int flag)
        mixed debug_info(int flag, mixed arg)
        mixed debug_info(int flag, mixed arg2, mixed arg3)

DESCRIPTION
        Gather some driver internal debug information according
        to the setting of flag:

        DINFO_OBJECT (0): Information like heart_beat, enable_commands
            etc. of the specified object will be printed, and 0 returned.

        DINFO_MEMORY (1): Memory usage information like how many strings,
            variables, inherited files, object size etc. will be printed
            about the specified object, and 0 returned.

        DINFO_OBJLIST (2): Objects from the global object list are
            returned.  If the optional <arg2> is omitted, the first
            element(s) (numbered 0) is returned. If the <arg2> is a
            number n, the n'th element(s) of the object list returned. If the
            <arg2> is an object, it's successor(s) in the object list is
            returned.
            The optional <arg3> specifies the maximum number of objects
            returned. If it's 0, a single object is returned. If it is
            a positive number m, an array with at max 'm' objects is
            returned. This way, by passing __INT_MAX__ as <arg3> it is
            possible to create an array of all objects in the game
            (given a suitable maximum array size).

        DINFO_MALLOC (3): Equivalent to typing ``malloc'' at the command
            line. No second arg must be given. Returns 0.

        DINFO_STATUS (4): Collect the status information of the driver.
            The optional second arg can be 0, "tables", "swap", "malloc"
            or any other argument accepted by the actual driver.
            The result is a printable string with the status information,
            or 0 if an invalid argument was given.

        DINFO_DUMP (5): Dump the information specified by <arg2> into the
            filename specified by <arg3>. If <arg3> is omitted, a default
            file name is used. The function calls master->valid_write() to
            check that it can write the files. The file in question is
            always written anew.

            Result is 1 on success, or 0 if an error occured.

            <arg2> == "objects": dump information about all live objects.
              Default filename is '/OBJ_DUMP', the valid_write() will read
              'objdump' for the function.

              For every object, a line is written into the file with the
              following information in the given order:
                - object name
                - size in memory, shared data counted only once
                - size in memory if data wouldn't be shared
                - number of references
                - 'HB' if the object has a heartbeat, nothing if not.
                - the name of the environment, or '--' if the object has no
                  environment
                - in parentheses the number of execution ticks spent in this
                  object
                - the swap status:
                   nothing if not swapped,
                   'PROG SWAPPED' if only the program is swapped
                   'VAR SWAPPED' if only the variabes are swapped
                   'SWAPPED' if both program and variables are swapped
                - the time the object was created

             <arg2> == "destructed": dump information about all destructed
               objects.  Default filename is '/DEST_OBJ_DUMP', the
               valid_write() will read 'objdump' for the function.

              For every object, a line is written into the file with the
              following information in the given order:
                - object name
                - number of references
                - 'NEW' if the object was destructed in this executiong
                  thread, nothing if it is older already.

            <arg2> == "opcodes": dump usage information about the opcodes.
              Default filename is '/OPC_DUMP', the valid_write() will read
              'opcdump' for the function.


        DINFO_DATA (6): Return raw information about an aspect of
            the driver specified by <arg2>. The result of the function
            is an array with the information, or 0 for unsupported values
            of <arg2>.

            If <arg3> is given and in the range of array indices
            for the given <arg2>, the result will be just the indexed array
            entry, but not the full array.

            Allowed values for <arg2> are: DID_STATUS, DID_SWAP, DID_MALLOC.

            <arg2> == DID_STATUS (0): Returns the "status" and "status tables"
            information. Following indices are defined:

              int DID_ST_BOOT_TIME
                  The time() when the mud was started.

              int DID_ST_ACTIONS
              int DID_ST_ACTIONS_SIZE
                  Number and size of allocated actions.

              int DID_ST_SHADOWS
              int DID_ST_SHADOWS_SIZE
                  Number and size of allocated shadows.

              int DID_ST_OBJECTS
              int DID_ST_OBJECTS_SIZE
                  Total number and size of objects.

              int DID_ST_OBJECTS_SWAPPED
              int DID_ST_OBJECTS_SWAP_SIZE
                  Number and size of swapped-out object variable blocks.

              int DID_ST_OBJECTS_LIST
                  Number of objects in the object list.

              int DID_ST_OBJECTS_NEWLY_DEST
                  Number of newly destructed objects (ie. objects destructed
                  in this execution thread).

              int DID_ST_OBJECTS_DESTRUCTED
                  Number of destructed but still referenced objects, not
                  counting the DID_ST_OBJECTS_NEWLY_DEST.

              int DID_ST_OBJECTS_PROCESSED
                  Number of listed objects processed in the last backend
                  cycle.

              float DID_ST_OBJECTS_AVG_PROC
                  Average number of objects processed each cycle, expressed
                  as percentage (0..1.0).

              int DID_ST_OTABLE
                  Number of objects listed in the object table.

              int DID_ST_OTABLE_SLOTS
                  Number of hash slots provided by the object table.

              int DID_ST_OTABLE_SIZE
                  Size occupied by the object table.

              int DID_ST_HBEAT_OBJS
                  Number of objects with a heartbeat.

              int DID_ST_HBEAT_CALLS
                  Number of active heart_beat cycles executed so far
                  (ie. cycles in which at least one heart_beat() function
                  was called).

              int DID_ST_HBEAT_CALLS_TOTAL
                  Total number of heart_beats cycles so far.

              int DID_ST_HBEAT_SLOTS
              int DID_ST_HBEAT_SIZE
                  Number of allocated entries in the heart_beat table
                  and its size.

              int DID_ST_HBEAT_PROCESSED
                  Number of heart_beats called in the last backend cycle.

              float DID_ST_HBEAT_AVG_PROC
                  Average number of heart_beats called each cycle, expressed
                  as fraction (0..1.0).

              int DID_ST_CALLOUTS
                  Number and total size of pending call_outs.

              int DID_ST_ARRAYS
              int DID_ST_ARRAYS_SIZE
                  Number and size of all arrays.

              int DID_ST_MAPPINGS
              int DID_ST_MAPPINGS_SIZE
                  Number and size of all mappings.

              int DID_ST_PROGS
              int DID_ST_PROGS_SIZE
                  Number and size of all programs.

              int DID_ST_PROGS_SWAPPED
              int DID_ST_PROGS_SWAP_SIZE
                  Number and size of swapped-out programs.

              int DID_ST_USER_RESERVE
              int DID_ST_MASTER_RESERVE
              int DID_ST_SYSTEM_RESERVE
                  Current sizes of the three memory reserves.

              int DID_ST_ADD_MESSAGE
              int DID_ST_PACKETS
              int DID_ST_PACKET_SIZE
                  Number of calls to add_message(), number and total size
                  of sent packets.
                  If the driver is not compiled with COMM_STAT, all three
                  values are returned as -1.

              int DID_ST_APPLY
              int DID_ST_APPLY_HITS
                  Number of calls to apply_low(), and how many of these
                  were cache hits.
                  If the driver is not compiled with APPLY_CACHE_STAT, all two
                  values are returned as -1.

              int DID_ST_STRINGS
              int DID_ST_STRING_SIZE
                  Number of distinct strings in the string table, and
                  their size.

              int DID_ST_STR_TABLE_SIZE
                  Size of the string table.

              int DID_ST_STR_REQ
              int DID_ST_STR_REQ_SIZE
                  Total number of string allocations, and their size.

              int DID_ST_STR_SEARCHES
              int DID_ST_STR_SEARCH_LEN
                  Number of searches in the string table, and the
                  accumulated search length.

              int DID_ST_STR_FOUND
                  Number successful searches.

              int DID_ST_STR_ENTRIES
                  Number of entries (hash chains) in the string table.

              int DID_ST_STR_ADDED
                  Number of strings added to the table so far.

              int DID_ST_STR_DELETED
                  Number of strings delete from the table so far.

              int DID_ST_STR_COLLISIONS
                  Number of strings added to an existing hash chain.

              int DID_ST_RX_CACHED
                  Number of regular expressions cached.

              int DID_ST_RX_TABLE
              int DID_ST_RX_TABLE_SIZE
                  Number of slots in the regexp cache table, and size of the
                  memory currently held by it and the cached expressions.

              int DID_ST_RX_REQUESTS
                  Number of requests for new regexps.

              int DID_ST_RX_REQ_FOUND
                  Number of requested regexps found in the table.

              int DID_ST_RX_REQ_COLL
                  Number of requested new regexps which collided with
                  a cached one.

              int DID_ST_MB_FILE
                  The size of the 'File' memory buffer.

              int DID_ST_MB_SWAP
                  The size of the 'Swap' memory buffer.


            <arg2> == DID_SWAP (1): Returns the "status swap" information:

               int DID_SW_PROGS
               int DID_SW_PROG_SIZE
                   Number and size of swapped-out program blocks.

               int DID_SW_PROG_UNSWAPPED
               int DID_SW_PROG_U_SIZE
                   Number and size of unswapped program blocks.

               int DID_SW_VARS
               int DID_SW_VAR_SIZE
                   Number and size of swapped-out variable blocks.

               int DID_SW_FREE
               int DID_SW_FREE_SIZE
                   Number and size of free blocks in the swap file.

               int DID_SW_FILE_SIZE
                   Size of the swap file.

               int DID_SW_REUSED
                   Total reused space in the swap file.

               int DID_SW_SEARCHES
               int DID_SW_SEARCH_LEN
                   Number and total length of searches for block to reuse
                   in the swap file.

               int DID_SW_F_SEARCHES
               int DID_SW_F_SEARCH_LEN
                   Number and total length of searches for a block to free.

               int DID_SW_COMPACT
                   TRUE if the swapper is running in compact mode.

               int DID_SW_RECYCLE_FREE
                   TRUE if the swapper is currently recycling free block.


            <arg2> == DID_MEMORY (2): Returns the "status malloc" information:

               string DID_MEM_NAME
                   The name of the allocator: "sysmalloc" or "smalloc".

               int DID_MEM_SBRK
               int DID_MEM_SBRK_SIZE
                   Number and size of memory blocks requested from the
                   operating system (smalloc only).

               int DID_MEM_LARGE
               int DID_MEM_LARGE_SIZE
               int DID_MEM_LFREE
               int DID_MEM_LFREE_SIZE
                   Number and size of large allocated resp. free blocks.
                   (smalloc only)

               int DID_MEM_LWASTED
               int DID_MEM_LWASTED_SIZE
                   Number and size of unusable large memory fragments.
                   (smalloc only).

               int DID_MEM_CHUNK
               int DID_MEM_CHUNK_SIZE
                   Number and size of small chunk blocks (smalloc only).

               int DID_MEM_SMALL
               int DID_MEM_SMALL_SIZE
               int DID_MEM_SFREE
               int DID_MEM_SFREE_SIZE
                   Number and size of small allocated resp. free blocks
                   (smalloc only).

               int DID_MEM_SWASTED
               int DID_MEM_SWASTED_SIZE
                   Number and size of unusably small memory fragments.
                   (smalloc only).

               int DID_MEM_MINC_CALLS
               int DID_MEM_MINC_SUCCESS
               int DID_MEM_MINC_SIZE
                   Number of calls to malloc_increment(), the number
                   of successes and the size of memory allocated this
                   way (smalloc only).

               int DID_MEM_PERM
               int DID_MEM_PERM_SIZE
                   Number and size of permanent (non-GCable) allocations
                   (smalloc only).

               int DID_MEM_CLIB
               int DID_MEM_CLIB_SIZE
                   Number and size of allocations done through the
                   clib functions (smalloc only with SBRK_OK).

               int DID_MEM_OVERHEAD
                   Overhead for every allocation (smalloc only).

               int DID_MEM_ALLOCATED
                   The amount of memory currently allocated from the
                   allocator, including the overhead for the allocator
                   (smalloc only).

               int DID_MEM_USED
                   The amount of memory currently used for driver data,
                   excluding the overhead from the allocator (smalloc only).

               int DID_MEM_TOTAL_UNUSED
                   The amount of memory allocated from the system, but
                   not used by the driver.


        DINFO_TRACE (7): Return the call stack 'trace' information as specified
            by <arg2>. The result of the function is either an array (format
            explained below), or a printable string. Omitting <arg2> defaults
            to DIT_CURRENT.

            <arg2> == DIT_CURRENT (0): Current call trace
                   == DIT_ERROR   (1): Most recent error call trace (caught
                                       or uncaught)
                   == DIT_UNCAUGHT_ERROR (2): Most recent uncaught-error call
                                              trace
               Return the information in array form.

               The error traces are changed only when an appropriate error
               occurs; in addition a GC deletes them. After an uncaught
               error, both error traces point to the same array (so the '=='
               operator holds true).

               If the array has more than one entries, the first entry is 0 or
               the name of the object with the heartbeat which started the
               current thread; all following entries describe the call stack
               starting with the topmost function called.

               All call entries are arrays themselves with the following
               elements:

               int[TRACE_TYPE]: The type of the call frame:
                   TRACE_TYPE_SYMBOL (0): a function symbol (shouldn't happen).
                   TRACE_TYPE_SEFUN  (1): a simul-efun.
                   TRACE_TYPE_EFUN   (2): an efun closure.
                   TRACE_TYPE_LAMBDA (3): a lambda closure.
                   TRACE_TYPE_LFUN   (4): a normal lfun.

               mixed[TRACE_NAME]: The 'name' of the called frame:
                   _TYPE_EFUN:   either the name of the efun, or the code of
                                 the instruction for operator closures
                   _TYPE_LAMBDA: the numeric lambda identifier.
                   _TYPE_LFUN:   the name of the lfun.

               string[TRACE_PROGRAM]: The (file)name of the program holding the
                   code.
               string[TRACE_OBJECT]:  The name of the object for which the code
                                      was executed.
               int[TRACE_LOC]:
                   _TYPE_LAMBDA: current program offset from the start of the
                                 closure code.
                   _TYPE_LFUN:   the line number.

            <arg2> == DIT_STR_CURRENT (3): Return the information about the
               current call trace as printable string.

HISTORY
        Since 3.2.7, DINFO_STATUS returns the status information instead
          of printing it.
        DINFO_DUMP introduced with 3.2.7.
        LDMud 3.2.8 added the data size of the object to the result of
          DINFO_MEMORY; the DINFO_DATA request; the DID_MEM_WASTED* stats.
        LDMud 3.2.9 added DINFO_TRACE; the indexing feature for DINFO_DATA;
          the 'destructed' DINFO_DUMP; the DID_MEM_CLIB*, DID_MEM_PERM*,
          DID_ST_OBJECTS_NEWLY_DEST, DID_ST_OBJECTS_DEST, DID_MEM_OVERHEAD,
          DID_MEM_ALLOCATED, DID_MEM_USED, DID_MEM_TOTAL_UNUSED,
          DID_ST_HBEAT_CALLS_TOTAL and the found/added/deleted/collisions
          string stats.
        LDMud 3.2.10 added the object creation time to DINFO_DUMP:"objects",
          removed DID_MEM_UNUSED from DINFO_DATA:DID_MEMORY; added
          DID_ST_BOOT_TIME, DID_ST_MB_FILE and DID_ST_MB_SWAP to
          DINFO_DATA:DID_STATUS; removed DID_ST_CALLOUT_SLOTS and from
          DINFO_DATA:DID_STATUS; added the third argument to
          DINFO_OBJLIST, and changed the meaning of
          DID_ST_CALLOUT_SIZE and DID_ST_HBEAT_SIZE/_SLOTS.

SEE ALSO
        trace(E), traceprefix(E), malloc(D), status(D), dumpallobj(D)
