unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



kdbx(8)								      kdbx(8)
Patchkit 5							   Patchkit 5



NAME

  kdbx - Analyzes running kernels and dump files

SYNOPSIS

  /usr/bin/kdbx	[-dbx dbx-path]	-k  [dbx-flags]	object-file [core-file]

DESCRIPTION

  The kdbx debugger is a crash analysis	and kernel debugging tool; it is an
  interactive program that serves as a front-end to the	dbx debugger.  The
  kdbx debugger	is extensible, customizable, and insensitive to	changes	of
  offsets and sizes of fields in structures. The only dependencies on kernel
  header files are for bit definitions in flag fields.

  The kdbx debugger lets you examine either the	running	kernel or dump files
  created by the savecore command. In either case, you examine an object file
  and a	core file.  For	running	systems, these files are usually /vmunix and
  /dev/mem, respectively.  Dump	files created by savecore are saved in the
  directory specified by the /sbin/init.d/savecore script. By default, the
  directory is /var/adm/crash.

  The kdbx debugger has	facilities for interpreting various symbols and	data
  structures.  It can format and display the symbols and data structures in
  the following	ways:

    +  In a predefined form as specified in the	modules	that currently accom-
       pany the	kdbx debugger

    +  As defined in user-written source code modules according	to a stand-
       ardized format for the contents of the kdbx modules

  All dbx commands are available through kdbx using the	dbx flag to kdbx.

  Defaults


  If you do not	specify	a core file, kdbx uses the dbx default of /dev/mem.
  Therefore, you can use kdbx with /vmunix as its only argument	to examine an
  active system. In general, kdbx assumes that addresses are specified in
  hexadecimal in commands that perform input or	output.

  When you begin a debugging session, kdbx executes the	commands in the	sys-
  tem initialization file /var/kdbx/SYSTEM.kdbxrc. The initialization file
  contains setup commands and alias definitions. The Aliases section lists
  the aliases defined in this file. You	can further customize the kdbx
  environment by adding	commands and aliases to	one of the following initial-
  ization files:

  /var/kdbx/SITE.kdbxrc
      Contains customized commands and alias definitions for a particular
      system.

  ~/.kdbxrc
      Contains customized commands and alias definitions for a specific	user.

  ./.kdbxrc
      Contains customized commands and alias definitions for a specific	pro-
      ject.  This file must reside in the current working directory when kdbx
      is invoked.

  Invocation


  To use kdbx to examine a running system, issue the following kdbx command:

       # kdbx -k /vmunix /dev/mem
       dbx version 3.11.1
       Type 'help' for help.

       stopped at  [thread_block:1403 ,0xfffffc000032e3c0]
				      Source not available
       (kdbx)

  To use kdbx to examine an object file	and core file created by the savecore
  utility, issue a kdbx	command	like the following one:

       # kdbx -k /usr/adm/crash/vmunix.1 /usr/adm/crash/dev/vmcore.1
       dbx version 3.11.1
       Type 'help' for help.

       stopped at  [thread_block:1403 ,0xfffffc000032e3c0]
				      Source not available
       (kdbx)

  In this case,	the version number in the bounds file is one.

  Commands


  The kdbx debugger provides the following commands:

  alias	[ name ] [ command-string ]
      Sets or displays aliases.	 If you	specify	the alias command without
      arguments, kdbx displays all aliases. If you specify only	the variable
      name, the	command	displays the alias for name, if	one exists. If you
      specify both name	and command-string, name is established	as an alias
      for command-string.

  context proc | user
      Sets the context to user's aliases or extension's	aliases. This command
      is used only by extensions.

  coredata start-address end-address
      Dumps, in	hexadecimal, the contents of the core file starting at
      start-address and	ending before end-address.

  dbx command-string
      Passes the variable command-string to dbx.  Specifying dbx is optional;
      if the command is	not recognized by kdbx,	it is passed to	dbx automati-
      cally.  See the dbx(1) reference page for	a complete description of the
      dbx commands.

  help [ -long ] [ arg ... ]
      Displays help text.

  proc [ flags ] [ extension ] [ arg ... ]
      Executes an extension and	gives it control of the	kdbx session until it
      quits.  The variable extension specifies the named extension file	and
      passes it	arguments as specified by the arg variables. Valid proc	flags
      are as follows:

      -debug
	  Causes I/O to	and from the extension to be displayed on the screen.

      -pipe in-pipe out-pipe
	  Used in conjunction with the dbx debugger for	debugging extensions.
	  The file in-pipe takes output	from the dbx session and directs it
	  as input to the kdbx session.	The file out-pipe takes	output from
	  the kdbx session and directs it as input to the dbx session.

      -print_output
	  Causes the output of the procedure to	be sent	to the invoker of the
	  procedure without interpretation as kdbx commands.

      -redirect_output
	  Used by extensions that execute other	extensions to receive the
	  output from the called extension instead of the user receiving it.

      -tty
	  Causes kdbx to talk to the subprocess	through	a tty line instead of
	  pipes.  If you also specify the -pipe	flag, proc ignores it.

  print	string
      Displays string on the terminal.	If this	command	is used	by an exten-
      sion, the	extension receives no output.

  quit
      Exits the	current	command	loop. If the current command loop is the top
      level loop that the user is using, kdbx exits.  Otherwise, control is
      given to the next	lowest loop.

  source [ -x ]	[ files	]
      Reads and	interprets files as kdbx commands in the context of the
      current aliases.	The -x flag causes commands to be displayed as they
      are executed.

  unalias name
      Removes an alias,	if any,	from name.

  Predefined kdbx Aliases


  The following	aliases	are defined in the kdbx	startup	file
  /var/kdbx/system.kdbxrc:

  __________________________________________________________________
  Alias		   Definition
  __________________________________________________________________
  arp		   "proc" arp
  array_action	   "proc" array_action
  buf		   "proc" buf
  buf_action	   list_action "struct buf *" b_forw buf buf
  callout_action   list_action "struct callout *" c_next 0 callout
  cast		   "proc" cast
  convert	   "proc" convert
  config	   "proc" config
  dis		   "proc" dis
  echo		   "proc" echo
  export	   "proc" export
  fields	   "proc" fields
  file		   "proc" file
  h		   help
  inpcb_action	   list_action "struct inpcb *"	inp_next
  list_action	   "proc" list_action
  mount_action	   list_action "struct mount *"	m_next rootfs rootfs
  mount		   "proc" mount
  namecache	   "proc" namecache
  ofile		   "proc" ofile
  paddr		   "proc" paddr
  pcb		   "proc" pcb
  pr		   "proc"
  printf	   "proc" printf
  proc		   "proc" proc
  procaddr	   "proc" procaddr
  procp		   "proc" -pipe	/tmp/pipein /tmp/pipeout
  procpd	   "proc" -debug -pipe /tmp/pipein /tmp/pipeout
  proc_action	   list_action "struct proc *" p_nxt 0 allproc
  ps		   "dbx" kps
  sh		   "proc" -print_output	-tty
  socket	   "proc" socket
  sum		   "proc" sum
  swap		   "proc" swap
  task		   "proc" task
  thread	   "proc" thread
  u		   "proc" u
  ucred		   "proc" ucred
  unaliasall	   "proc" unaliasall
  vnode		   "proc" vnode
  __________________________________________________________________

  Extensions


  For extensions that display addresses	as part	of their output, some use a
  shorthand notation for the upper 32-bits of an address to keep the output
  readable.  The following table lists the notation for	each address type.

  __________________________________________________________
  Notation   Address Type	      Replaces	 Example
  __________________________________________________________
  v	     virtual		      ffffffff	 v0x902416f0
  k	     kseg		      fffffc00	 k0x363076f4
  u	     user space		      00000000	 u0x86406200
  ?						 ?0x0033aa24

	     Unrecognized or random
	     type
  __________________________________________________________

  The extensions available to kdbx are as follows:

  arp [	- ]
      Displays the contents of the address resolution protocol (arp) table.
      If you specify the optional hyphen (-), arp displays the entire arp
      table; otherwise,	arp displays those entries that	have nonzero
      at_iaddr.s_addr and at_flags fields.

  array_action "type" length start_address [ flags ] command
      Performs a command action	on each	element	of an array. This extension
      allows you to step through any array in the operating system kernel and
      display specific components or values as described in the	list of	com-
      mand flags.  The arguments to the	array_action extension are as fol-
      lows:

      "type"
	  The type of address of the array element.

      length
	  The number of	elements in the	array.

      start_address
	  The address of the array. A variable name or a number	can be used
	  to specify start_address. The	more common syntax or notation used
	  to refer to the start_address	is usually of the form &&arrayname[0].

      flags
	  Valid	flags for the array_action extension are as follows:

	  -head
	      If you specify the -head flag, kdbx displays the next argument
	      as the table header.

	  -size
	      If you specify the -size flag, kdbx uses the next	argument as
	      the array	element	size. Otherwise, kdbx calculates the size
	      from the element type.

	  -cond
	      If you specify the -cond flag, kdbx uses the next	argument as a
	      filter.  The dbx debugger	evaluates the condition	for each
	      array element, and if it evaluates to TRUE, takes	the action on
	      the array	element.  The same substitutions that are applied to
	      the command are applied to the condition.

      command
	  The name of the kdbx or dbx command that is to be performed on each
	  element of the array.

      Note that	the kdbx debugger includes several aliases, such as
      file_action, that	might be easier	to use than directly using the
      array_action extension.

      Substitutions similar to printf can be performed on the command for
      each array element.  The possible	substitutions are as follows:


      %a   Address of element
      %c   Cast	of address to pointer to array element
      %i   Index of element within the array
      %s   Size	of element
      %t   Type	of pointer to element

  buf [	address	| -free	| -all ]
      Displays the buffer table.  If no	arguments are specified, the buffers
      on the hash list are displayed.

      If addresses are specified, the buffers at those addresses are
      displayed.  If you specify the -free flag, kdbx displays all the
      buffers on the free list.	 If you	specify	the -all flag, kdbx displays
      buffers on the hash list first, followed by buffers on the free list.

  callout
      Displays the callout table.

  cast address type
      Forces dbx to display a piece of memory as a given type. This extension
      is equivalent to dbx print *((type)address).

  config
      Displays the configuration of the	machine.

  convert [ -in	8 | 10 | 16 ] -out 2 | 8 | 10 |	16 [ args ]
      Converts numbers from one	base to	another. The -in and -out flags
      specify the input	and output bases, respectively.	If you omit -in, kdbx
      infers the input base from the arguments.	The arguments can be either
      numbers or variables.

  cpustat [ -update n ]
      Displays CPU use statistics on a per-CPU basis. If you specify -update,
      kdbx updates the display every n seconds.

  dis start-address [ num-instructions ]
      Disassembles some	number of instructions as specified in the num-
      instructions instructions	starting at start-address. If you omit the
      number of	instructions, kdbx disassembles	one instruction.

  export
      Displays the exported entries that are mounted remotely.

  file [ addresses ]
      Displays the file	table.	If no addresses	are specified, all file
      entries with nonzero reference counts are	displayed. Otherwise, the
      file entries at the specified addresses are displayed.

  inpcb	[ -udp ] [ -tcp	] [ addresses ]
      Displays the udb and tcb tables. If no arguments are specified, both
      tables are displayed.  If	you specify either -udp	or -tcp, kdbx
      displays the corresponding table.

      If addresses are specified, -udp and -tcp	are ignored and	the entries
      at the specified addresses are displayed.

  list_action "type" next-field	end-addr start-addr

  [ flags ] command
      Performs some command on each element of a linked	list.  This extension
      makes it possible	to walk	through	any linked list	in the operating sys-
      tem kernel and display particular	components while walking through the
      linked list.  The	arguments to the list_action extension are as fol-
      lows:

      "type"
	  The type of address of an element in the specified list.

      next-field
	  The name of the field	that points to the next	element.

      end-addr
	  The value of the next	field that terminates the list.	If the list
	  is NULL-terminated, the value	of end-addr is 0.  If the list is
	  circular, the	value of end-addr is equal to start-addr.

      start_address
	  The address of a list.  The address can be specified as a variable
	  name or a number.

      flags
	  Valid	flags for the list_action extension are	as follows:

	  -head	header
	      If you specify the -head header flag, kdbx displays the header
	      argument as the table header.

	  -cond
	      If you specify -cond, the	next arg is used as a filter.  The
	      dbx debugger evaluates the condition for each list element, and
	      if it evaluates to true, takes the action	on the list element.
	      The same substitutions that are applied to the command are
	      applied to the condition.

      command
	  The kdbx or dbx command to perform on	each element of	the list.

      Note that	kdbx includes several aliases, such as file_action, that
      might be easier to use than directly using the list_action extension.

      Substitutions similar to printf substitutions are	performed on the com-
      mand for each element.  The possible substitutions are as	follows:


      %a   Address of element
      %c   Cast	of address to pointer to list element
      %i   Index of element within the list
      %n   Name	of next	field
      %t   Type	of pointer to element

  lockinfo [-class name]
      Displays the static lock type information	contained in the lockinfo
      structures.  This	extension is available only when the lockmode system
      attribute	is set to four.	The -class flag	allows you to display infor-
      mation about a particular	class of locks.

  lockstats [-class name -cpu number -read -sum	-total -update n]
      Displays statistics about	locks recorded in the lockstats	structure.
      These statistics are dynamic.  This extension is available only when
      the lockmode system attribute is set to four.

      Statistics displayed include information about the number	of instances
      of a particular lock type, the number of times processes tried to	get a
      lock type, the number of times processes tried and failed	to get a par-
      ticular lock type	and the	amount of time spent waiting for locks.

      The flags	for the	lockstats extension are	as follows:

      -class name
	  Displays the lockstats structures of the specified lock type

      -cpu number
	  Displays the lockstats structures associated with the	specified CPU

      -read
	  Displays the reads, sleeps attributes, and summary of	time spent
	  waiting or number of misses

      -sum
	  Displays summary data	for all	CPUs and all lock types

      -total
	  Displays summary data	for all	CPUs

      -update n
	  Updates the display every n seconds

  mount	[ -s ] [ address ]
      Displays the mount table.	The -s flag outputs a short form of the
      table.  If addresses are specified, the mount entries at the specified
      addresses	are displayed.

  namecache [-neg | -all -p cpu	] [ -v vpid | -d dvpid | -n name ]
      Displays the per-processor namecache entries on the system. If no	flags
      are specified, namecache entries on the primary cpu are displayed. The
      flags for	the namecache extension	are as follows:

      -h	  Displays the list of flags, usage information, and tips.

      -help	  Displays the list of flags and usage information.

      -neg	  Displays the namecache entries of the	global negative
		  namecache list.

      -all	  Displays the namecache entries, including negative name-
		  cache	entries.

      -p cpu	  Displays the namecache entries on the	specified cpu.

      -v vpid	  Displays the namecache entries with the specified vpid.

      -d dvpid	  Displays the namecache entries under the directory with the
		  specified dvpid.

      -n name	  Displays the namecache entries with the specified name.

      For example, to see all the negative entries on processor	1:
	   kdbx>> namecache -v 0	-p 1 -all

      To see all the entries with the filename Makefile	on processor 2:
	   kdbx>> namecache -p 2	-n Makefile

  netstat -i [ -a ] [ -t ] [ -n	] [ -d ]
      Displays the state of the	network	interfaces. The	optional flags for
      the netstat extension are	as follows:

      -a  Displays the IP and link-level addresses.

      -t  Displays timer information.

      -n  Displays network addresses in	numeric	formal.

      -d  Displays the number of dropped packets.

  ofile	[ -proc	address	| -pid pid | -v	]
      Displays the files opened	by processes.  If no arguments are specified,
      the extension displays the files opened by each process. If you specify
      either -proc address or -pid pid,	kdbx displays the open files of	the
      given process. The -v flag displays more information about the open
      files.

  paddr	address	number-of-longwords
      Converts a range of memory to symbolic references. The argument address
      is the starting address. The argument number-of-longwords	is the number
      of words to dump out.

  pcb thread_address
      Displays the process control block for a given thread at the specified
      address. For integer and floating-point registers, only nonzero con-
      tents are	displayed.

  printf format-string [ args ]
      Formats one argument at a	time to	work around the	dbx debugger's com-
      mand length limitation.  It also implements the %s string	substitution,
      which the	dbx printf command does	not.  The argument format-string
      specifies	a character string combining literal characters	with conver-
      sion specifications.

  proc [ addresses ]
      Displays the process table.  If addresses	are specified, the proc
      structures at the	specified addresses are	displayed. Otherwise, all
      proc structures are displayed.

  procaddr [ address ]
      Converts the specified address to	a procedure name.

  route	[ -v ] [ -n ] [	-R ] [ -H ]
      Displays the route and Address Resolution	Protocol (ARP) tables. The
      optional flags for the route extension are as follows:

      -A  Print	addresses of data structures

      -v  Print	verbose	route or ARP tables.

      -n  Display network addresses in numeric format.

      -R  Display route	information on all Resource Affinity Domains (RADs).

      -H  Display ARP tables.

  socket
      Displays the files that are sockets with nonzero reference counts	in
      the file table.

  sum Displays a summary of the	system.

  swap
      Displays a summary of swap space.

  task [ proc_addresses	]
      Displays the task	structures associated with the specified addresses.
      If no addresses are specified, all tasks are displayed.

  thread [ proc_addresses ]
      Displays information about the threads associated	with the specified
      addresses. If no addresses are specified,	all threads are	displayed.

  trace	[ thread_address... | -k | -u |	-a ]
      Displays the stack trace of one or more threads.	If you specify
      thread_address, the extension displays the stack trace of	the specified
      thread. If you omit the argument and all the flags, trace	displays the
      stack trace of all threads.  You can specify the following flags:

      -a  Display the stack trace of the active	thread on each CPU.

      -k  Display the stack trace of all kernel	threads.

      -u  Display the stack trace of all user threads.

      -buf
	  Display all ucred structures referenced by the buf structures.

      -ref address
	  Display all references to a given ucred structure.

      -check address
	  Check	the reference count of a particular ucred structure.

      -checkall
	  Check	the reference count of all ucred structures (mismatch marked
	  by *).

  u [ proc_address ]
      Displays a u structure at	the address proc-addr.

  ucred	[ -proc	| -uthread | -file |-buf |

  -ref address | -check	address	| -checkall ]
      Displays or checks references to ucred structures.  If no	flags are
      specified, this extension	displays all references	to ucred structures
      on the system. Possible flags are	as follows:

      -proc
	  Display all ucred structures referenced by the proc structures.

      -uthread
	  Display all ucred structures referenced by the uthread structures.

      -file
	  Display all ucred structures referenced by the file structures.

      -buf
	  Display all ucred structures referenced by the buf structures.

      -ref address
	  Display all references to a given ucred structure.

      -check address
	  Check	the reference count of a particular ucred structure.

      -checkall
	  Check	the reference count of all ucred structures (mismatch marked
	  by *).

  unaliasall
      Removes all aliases including the	predefined aliases described in	the
      Predefined kdbx Aliases section.

  vnode	[ -free	| -all | -ufs |	-nfs | -cdfs |

  -fs address |	-u uid | -g gid	| -v ]
      Displays the vnode table.	If no arguments	are specified, all ACTIVE
      vnodes on	the system are displayed. ACTIVE means nonzero usecount	or
      nonzero holdcnt.	Possible flags are listed as follows:

      -free
	  Display INACTIVE (both usecount and holdcnt are zeros) entries in
	  the vnode table.

      -all
	  Display ALL (both ACTIVE and INACTIVE) entries in the	vnode table.

      -ufs
	  Display all UFS vnodes.

      -nfs
	  Display all NFS vnodes.

      -cdfs
	  Display all CDFS vnodes.

      -fs address
	  Display vnode	entries	of a mounted file system.

      -u uid
	  Display vnode	entries	of a particular	user.

      -g gid
	  Display vnode	entries	of a particular	group.

      -v  Display related inode/rnode/cdnode information (used with -ufs,
	  -nfs,	or -cdfs only).









SEE ALSO

  Commands: dbx(1), savecore(8)


  Kernel Debugging

  Programmer's Guide