redir_debug_init

Syntax

#include <debug/redir.h> int redir_debug_init (cmdline_t *cmd);

Description

This function initializes the data structure in the cmd variable required to save and restore debugger's standard handles across invocations of run_child (see section run_child). The debugger will then typically call redir_to_child and redir_to_debugger.

These functions are needed when a debugger wants to redirect standard handles of the debuggee, or if the debuggee redirects some of its standard handles, because the debuggee is not a separate process, we just pretend it is by jumping between two threads of execution. But, as far as DOS is concerned, the debugger and the debuggee are a single process, and they share the same Job File Table (JFT). The JFT is a table maintained by DOS in the program's PSP where, for each open handle, DOS stores the index into the SFT, the System File Table. (The SFT is an internal data structure where DOS maintains everything it knows about a certain open file/device.) A handle that is returned by open, _open and other similar functions is simply an index into the JFT where DOS stored the SFT entry index for the file or device that the program opened.

When a program starts, the first 5 entries in the JFT are preconnected to the standard devices. Any additional handles opened by either the debugger or the debuggee use handles beyond the first 5 (unless one of the preconnected handles is deliberately closed). Here we mostly deal with handles 0, 1 and 2, the standard input, standard output, and standard error; they all start connected to the console device (unless somebody redirects the debugger's I/O from the command line).

Since both the debugger and the debuggee share the same JFT, their handles 0, 1 and 2 point to the same JFT entries and thus are connected to the same files/devices. Therefore, if the debugger redirects its standard output, the standard output of the debuggee is also automagically redirected to the same file/device! Similarly, if the debuggee redirects its stdout to a file, you won't be able to see debugger's output (it will go to the same file where the debuggee has its output); and if the debuggee closes its standard input, you will lose the ability to talk to debugger!

The debugger redirection support attempts to solve all these problems by creating an illusion of two separate sets of standard handles. Each time the debuggee is about to be run or resumed, it should call redir_to_child to redirect debugger's own standard handles to the file specified in the command-line (as given by e.g. the "run" command of GDB) before running the debuggee, then call redir_to_debugger to redirect them back to the debugger's original input/output when the control is returned from the debuggee (e.g. after a breakpoint is hit). Although the debugger and the debuggee have two separate copies of the file-associated data structures, the debugger still can redirect standard handles of the debuggee because they use the same JFT entries as debugger's own standard handles.

The cmdline_t structure is declared in the header `debug/redir.h' as follows:

struct dbg_redirect { int inf_handle; /* debuggee's handle */ int our_handle; /* debugger's handle */ char *file_name; /* file name where debuggee's handle is * redirected */ int mode; /* mode used to open() the above file */ off_t filepos; /* file position of debuggee's handle; unused */ }; typedef struct _cmdline { char *command; /* command line with redirection removed */ int redirected; /* 1 if handles redirected for child */ struct dbg_redirect **redirection;/* info about redirected handles */ } cmdline_t;

In the cmdline_t structure, the redirection member points to an array of 3 dbg_redirect structures, one each for each one of the 3 standard handles. The inf_handle and our_handle members of those structures are used to save the handle used, respectively, by the debuggee (a.k.a. the inferior process) and by the debugger.

The cmd variable is supposed to be defined by the debugger's application code. redir_debug_init is called to initialize that variable. It calls redir_cmdline_delete to close any open handles held in cmd and to free any allocated storage; then it fills cmd with the trivial information (i.e., every standard stream is connected to the usual handles 0, 1, and 2).

Return Value

redir_debug_init returns zero in case of success, or -1 otherwise.

Portability

ANSI/ISO C	No
POSIX	No

Example

if (redir_debug_init (&child_cmd) == -1) fatal ("Cannot allocate redirection storage: not enough memory.\n");