gdb_examine

Instructions

Implementation Reference

• src/index.ts:1068-1109 (handler)

  Core handler function for the 'gdb_examine' tool. It validates the session, constructs the GDB examine command 'x/{count}{format} {expression}', executes it, and formats the response.

  private async handleGdbExamine(args: any) {
    const { sessionId, expression, format = 'x', count = 1 } = args;
    
    if (!activeSessions.has(sessionId)) {
      return {
        content: [
          {
            type: 'text',
            text: `No active GDB session with ID: ${sessionId}`
          }
        ],
        isError: true
      };
    }
    
    const session = activeSessions.get(sessionId)!;
    
    try {
      // Format examine command: x/[count][format] [expression]
      const command = `x/${count}${format} ${expression}`;
      const output = await this.executeGdbCommand(session, command);
      
      return {
        content: [
          {
            type: 'text',
            text: `Examine ${expression} (format: ${format}, count: ${count}):\n\n${output}`
          }
        ]
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: 'text',
            text: `Failed to examine memory: ${errorMessage}`
          }
        ],
        isError: true
      };
    }

• src/index.ts:312-332 (schema)

  Input schema definition for the gdb_examine tool, specifying required sessionId and expression, optional format and count.

  inputSchema: {
    type: 'object',
    properties: {
      sessionId: {
        type: 'string',
        description: 'GDB session ID'
      },
      expression: {
        type: 'string',
        description: 'Memory address or expression'
      },
      format: {
        type: 'string',
        description: 'Display format (e.g., "x" for hex, "i" for instruction)'
      },
      count: {
        type: 'number',
        description: 'Number of units to display'
      }
    },
    required: ['sessionId', 'expression']

• src/index.ts:309-334 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and inputSchema for gdb_examine.

  {
    name: 'gdb_examine',
    description: 'Examine memory',
    inputSchema: {
      type: 'object',
      properties: {
        sessionId: {
          type: 'string',
          description: 'GDB session ID'
        },
        expression: {
          type: 'string',
          description: 'Memory address or expression'
        },
        format: {
          type: 'string',
          description: 'Display format (e.g., "x" for hex, "i" for instruction)'
        },
        count: {
          type: 'number',
          description: 'Number of units to display'
        }
      },
      required: ['sessionId', 'expression']
    }
  },

• src/index.ts:387-388 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement, routing gdb_examine calls to the handler.

  case 'gdb_examine':
    return await this.handleGdbExamine(request.params.arguments);

• src/index.ts:1159-1217 (helper)

  Shared helper function that executes GDB commands over stdin/stdout and captures/parses the output, used by gdb_examine handler.

  private executeGdbCommand(session: GdbSession, command: string): Promise<string> {
    return new Promise<string>((resolve, reject) => {
      if (!session.ready) {
        reject(new Error('GDB session is not ready'));
        return;
      }
      
      // Write command to GDB's stdin
      if (session.process.stdin) {
        session.process.stdin.write(command + '\n');
      } else {
        reject(new Error('GDB stdin is not available'));
        return;
      }
      
      let output = '';
      let responseComplete = false;
      
      // Create a one-time event handler for GDB output
      const onLine = (line: string) => {
        output += line + '\n';
        
        // Check if this line indicates the end of the GDB response
        if (line.includes('(gdb)') || line.includes('^done') || line.includes('^error')) {
          responseComplete = true;
          
          // If we've received the complete response, resolve the promise
          if (responseComplete) {
            // Remove the listener to avoid memory leaks
            session.rl.removeListener('line', onLine);
            resolve(output);
          }
        }
      };
      
      // Add the line handler to the readline interface
      session.rl.on('line', onLine);
      
      // Set a timeout to prevent hanging
      const timeout = setTimeout(() => {
        session.rl.removeListener('line', onLine);
        reject(new Error('GDB command timed out'));
      }, 10000); // 10 second timeout
      
      // Handle GDB errors
      const errorHandler = (data: Buffer) => {
        const errorText = data.toString();
        output += `[stderr] ${errorText}\n`;
      };
      
      // Add error handler
      if (session.process.stderr) {
        session.process.stderr.once('data', errorHandler);
      }
      
      // Clean up event handlers when the timeout expires
      timeout.unref();
    });
  }