dmalloc.1

   1 .TH DMALLOC 1
   2 .SH NAME
   3 dmalloc \- program used to set the environment for debugging using the
   4 dmalloc debugging library.
   5 .SH SYNOPSIS
   6 .B dmalloc
   7 .I [options]
   8 .SH "DESCRIPTION"
   9 This manual page documents the
  10 .BR dmalloc
  11 command.
  12 It was written for the Debian GNU/Linux distribution based, almost verbatim,
  13 on the original documentation provided by the library in GNU Info format;
  14 see below.
  15 .PP
  16 The
  17 .B dmalloc
  18 program is designed to assist in the setting of the
  19 environment variable
  20 .B DMALLOC_OPTIONS.
  21 It is designed to print the shell commands necessary to make the
  22 appropriate changes to the environment.  Unfortunately, it cannot make
  23 the changes on its own so the output from dmalloc should be sent
  24 through the `eval' shell command which will do the commands.
  25
  26 With shells that have aliasing or macro capabilities: csh, bash, ksh,
  27 tcsh, zsh, etc., setting up an alias to dmalloc to do the eval call is
  28 recommended.  Csh/tcsh users (for example) should put the following in
  29 their `.cshrc' file:
  30
  31 alias dmalloc 'eval `\dmalloc -C \!*`'
  32
  33 Bash and Zsh users on the other hand should put the following in
  34 their `.zshrc' file:
  35
  36 function dmalloc { eval `command dmalloc -b $*` }
  37
  38 This allows the user to execute the dmalloc command as `dmalloc
  39 arguments'.
  40
  41 The most basic usage for the program is
  42 .B `dmalloc [-bC] tag'.
  43  The
  44 .B `-b'
  45 or
  46 .B `-C'
  47 (either but not both flags used at a time) are for
  48 generating Bourne or C shell type commands respectively.  dmalloc will
  49 try and use the
  50 .B `SHELL'
  51 environment variable to determine whether
  52 bourne or C shell commands should be generated but you may want to
  53 explicitly specify the correct flag.
  54
  55 The
  56 .I tag
  57 argument to dmalloc should match a line from the user's
  58 run-time configuration file or should be one of the built-in tags.
  59 If no tag is specified and no other option-commands
  60 used, dmalloc will display the current settings of the environment
  61 variable.  It is useful to specify one of the verbose options when doing
  62 this.
  63
  64 To find out the usage for the debug malloc program try
  65 .B dmalloc \-\-usage\-long.
  66 The standardized usage message that will be displayed is
  67 one of the many features of the argv library included with this package.
  68 It is available via ftp from `ftp.letters.com' in the `/src/argv'
  69 directory.  See `argv.info' there for more information.
  70
  71 .SH OPTIONS
  72 .TP
  73 .B \-a
  74 .I address
  75 Set the `addr' part of the
  76 .B DMALLOC_OPTIONS
  77 variable to address (or alternatively address:number).
  78 .TP
  79 .B \-b
  80 Output Bourne shell type commands.
  81 .TP
  82 .B \-C
  83 Output C shell type commands.
  84 .TP
  85 .B \-c
  86 Clear/unset all of the settings not specified with other arguments.
  87 Clear will never unset the `debug' setting.  Use
  88 .B \-d 0
  89 or a tag to `none' to achieve this.
  90 .TP
  91 .B \-d
  92 .I bitmask
  93 Set the `debug' part of the
  94 .B DMALLOC_OPTIONS
  95 env variable to the
  96 bitmask value which should be in hex.  This is overridden (and
  97 unnecessary) if a tag is specified.
  98 .TP
  99 .B \-D
 100 List all of the debug-tokens.  Useful for finding a token to be
 101 used with the
 102 .B \-p
 103 or
 104 .B \-m
 105 options.  Use with
 106 .B \-v
 107 or
 108 .B \-V
 109 verbose options.
 110 .TP
 111 .B \-e
 112 .I errno
 113 Print the dmalloc error string that corresponds to the error number
 114 errno.
 115 .TP
 116 .B \-f
 117 .I filename
 118 Use this configuration file instead of the RC file
 119 .I ~/.dmallocrc.
 120 .TP
 121 .B \-i
 122 .I number
 123 Set the checking interval to number.
 124 .TP
 125 .B \-k
 126 Keep the settings when using a tag.  This overrides
 127 .B \-r .
 128 .TP
 129 .B \-l
 130 .I filename
 131 Set the log-file to filename.
 132 .TP
 133 .B \-L
 134 Output the debug-value not in hex but by individual debug-tokens
 135 in long form.
 136 .TP
 137 .B \-m
 138 .I token(s)
 139 Remove (minus) the debug capabilities of token(s) from the current
 140 debug setting or from the selected tag (or
 141 .B \-d
 142 value).  Multiple
 143 .B \-m's
 144 can be specified.
 145 .TP
 146 .B \-n
 147 Without changing the environment, output the commands resulting
 148 from the supplied options.
 149 .TP
 150 .B \-p
 151 .I token(s)
 152 Add (plus) the debug capabilities of token(s) to the current debug
 153 setting or to the selected tag (or
 154 .B \-d
 155 value).  Multiple
 156 .B \-p's
 157 can be
 158 specified.
 159 .TP
 160 .B \-r
 161 Remove (unset) all settings when using a tag.  This is useful when
 162 you are returning to a standard development tag and want the
 163 logfile, address, and interval settings to be cleared
 164 automatically.  If you want this behavior by default, this can be
 165 put into the dmalloc alias.
 166 .TP
 167 .B \-s
 168 .I number
 169 Set the `start' part of the
 170 .B DMALLOC_OPTIONS
 171 env variable to
 172 number (alternatively `file:line').
 173 .TP
 174 .B \-S
 175 Output the debug-value not in hex but by individual debug-tokens
 176 in short form.
 177 .TP
 178 .B \-t
 179 List all of the tags in the rc-file.  Use with
 180 .B \-v
 181 or
 182 .B \-V
 183 verbose options.
 184 .TP
 185 .B \-v
 186 Give verbose output.  Especially useful when dumping current
 187 settings or listing all of the tags.
 188 .PP
 189 If no arguments are specified, dmalloc dumps out the current settings
 190 that you have for the environment variable.  For example:
 191
 192      Debug-Flags  '0x40005c7' (runtime)
 193      Address      0x1f008, count = 3
 194      Interval     100
 195      Logpath      'malloc'
 196      Start-File   not-set
 197
 198 With a
 199 .B -v
 200 option and no arguments, dmalloc dumps out the current
 201 settings in a verbose manner.  For example:
 202
 203      Debug-Flags  '0x40005c7' (runtime)
 204         log-stats, log-non-free, log-blocks, log-unknown,
 205         log-bad-space, check-fence, catch-null
 206      Address      0x1f008, count = 10
 207      Interval     100
 208      Logpath      'malloc'
 209      Start-File   not-set
 210
 211 .SH "SEE ALSO"
 212 The documetation for the library is in GNU Info format. Please check the
 213 file
 214 .IR /usr/info/dmalloc.info.gz
 215 for more details.
 216
 217 .SH FILES
 218 .TP
 219 .I /usr/info/dmalloc.info.gz
 220 The real documentation for the dmalloc library.
 221 .TP
 222 .I ~/.dmallocrc
 223 User's configuration file.
 224 .SH AUTHOR
 225 This manual page was written by Luis Francisco González <luisgh@debian.org>,
 226 for the Debian GNU/Linux system (but may be used by others).
 227 The library was written by
 228 .B Gray Watson.
 229 Please see the copyright
 230 file in
 231 .I /usr/doc/dmalloc
 232 for details.