gcore.tproj/gcore-internal.1

   1 .Dd 9/29/16
   2 .Dt gcore-internal 1
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm gcore
   6 .Nd get core images of running processes and corpses
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Op Fl x
  10 .Op Fl F
  11 .Op Fl C
  12 .Op Fl Z Ar compopts
  13 .Op Fl t Ar threshold
  14 .Op Fl d
  15 .Ar args ...
  16 .Nm
  17 .Sy conv
  18 .Op Fl L Ar searchpath
  19 .Op Fl z
  20 .Op Fl v
  21 .Op Fl d
  22 .Ar incore outcore
  23 .Nm
  24 .Sy map
  25 .Ar corefile
  26 .Nm
  27 .Sy fref
  28 .Ar corefile
  29 .Sh DESCRIPTION
  30 For an introduction to this command and its options, see
  31 .Xr gcore 1 .
  32 This page describes various experimental capabilities
  33 of the
  34 .Nm
  35 command intended, for the moment, for internal use only.
  36 .Pp
  37 The following set of additional flags are available:
  38 .Bl -tag -width Fl
  39 .It Fl x
  40 Create extended (compact) core files.  With this flag,
  41 .Nm
  42 elides empty and unmapped regions from the dump, and uses
  43 metadata from the VM system and
  44 .Xr dyld 1
  45 to minimize the size of the dump, writing compressed versions of
  46 the active regions of the address space into the dump file.
  47 .Nm
  48 also records file references to the various files mapped into the
  49 address space, potentially including the shared cache, to
  50 avoid duplicating content already present on the filesystem.
  51 Taken together, these techniques can lead to very significant
  52 space savings for the core file, particularly for smaller programs.
  53 .It Fl F
  54 Normally when
  55 .Fl x
  56 is specified,
  57 .Nm
  58 makes conservative assumptions about which files should be
  59 incorporated into the dump as file references so that the
  60 full core file can be recreated later.  This flag attempts to make
  61 .Em every
  62 mapped file into a file reference.  While this can occasionally
  63 be useful for applications that map many files into their address space,
  64 it may be
  65 .Em extremely
  66 difficult to recreate the process image as a result.
  67 Use cautiously!
  68 .El
  69 .Pp
  70 The remaining options are more relevant to the
  71 .Nm
  72 maintainers:
  73 .Bl -tag -width Fl
  74 .It Fl C
  75 Forcibly generate a corpse for the process, even if the process is suspended.
  76 .It Fl Z Ar compopts
  77 Specify compression options e.g. algorithm and chunksize.
  78 .It Fl t Ar threshold
  79 Set the threshold at which I/O caching is disabled to
  80 .Ar threshold
  81 KiBytes.
  82 .It Fl d
  83 Enable debugging of the
  84 .Nm
  85 command.
  86 .El
  87 .Pp
  88 If the
  89 .Ar pid
  90 value is specified as 0,
  91 .Nm
  92 assumes it has been passed a corpse port by its parent;
  93 if so it will generate a core dump for that corpse.  The
  94 .Fl c
  95 flag may not be used in this case, as the process context may no longer exist.
  96 .Pp
  97 The
  98 .Nm
  99 command supports several sub-commands that can be
 100 used with extended core files created using the
 101 .Fl x
 102 flag.  These are:
 103 .Bl -tag -width frefs
 104 .\" -compact -offset indent
 105 .Pp
 106 .It Sy conv
 107 Copy and convert a core file to the "pre-coreinfo" format
 108 compatible with
 109 .Xr lldb(1) .
 110 This operation reads the input core file dereferencing any file
 111 references it contains by copying the content
 112 and decompressing any compressed data into the output core file.
 113 This conversion usually makes the core file substantially larger.
 114 .Pp
 115 Files to be dereferenced must be accessible on the
 116 local filesystem by the same relative paths as they were originally recorded
 117 when the dump was taken.
 118 Files that are Mach-O objects containing UUIDs are required to match
 119 the UUIDs recorded at the time the core dump was taken.
 120 Files are otherwise only checked for matching modification times, and
 121 thus can easily be "forged" using
 122 .Xr touch 1 .
 123 .Pp
 124 Several flags can be used with the conversion:
 125 .Pp
 126 .Bl -tag -width Fl
 127 .It Fl L Ar searchpath
 128 When processing file references,
 129 look for the pathnames in the directories specified in
 130 .Ar searchpath .
 131 These should be specified as a colon-separated
 132 list of base directories which will be prepended to each pathname in turn
 133 for each file reference.
 134 .It Fl z
 135 During conversion, if any mapped file
 136 identified by modification time
 137 cannot be located, substitute zeroed memory.
 138 .It Fl v
 139 Report progress on the conversion as it proceeds.
 140 .It Fl d
 141 Enable debugging of the
 142 .Sy conv
 143 subcommand.
 144 .El
 145 .It Sy map
 146 Print a representation of the address space contained in the core file.
 147 .Pp
 148 .It Sy frefs
 149 Print a list of files corresponding to the file references
 150 in the core file.
 151 Can be used to capture the set of files needed to bind the file references
 152 into the core file at a later time.
 153 .El
 154 .Sh BUGS
 155 .Pp
 156 When using the
 157 .Fl x
 158 flag,
 159 .Nm
 160 will likely incorporate a reference to the shared cache into
 161 .Ar corefile
 162 including the UUID of that cache.
 163 On some platforms, the cache is created when the release is built
 164 and since it resides on a read-only root filesystem it should
 165 generally be easy to retrieve.
 166 However on the desktop, the lifecycle of this cache is managed locally
 167 e.g. with
 168 .Xr update_dyld_shared_cache 1.
 169 When this cache is recreated it is given a new UUID, the directory
 170 entry for the old cache is removed, and the same filename
 171 is used for the new cache.
 172 Thus when the last named copy of the shared cache is removed from the
 173 filesystem, extended core files that contain references to that cache
 174 can no longer be converted.
 175 .Pp
 176 When using the
 177 .Fl x
 178 flag,
 179 .Nm
 180 may be unable to locate the currently mapped shared cache in the filesystem.
 181 In this case
 182 .Nm
 183 does not generate any file references to the content of the
 184 shared cache; it just copies as much of the content
 185 as is needed from the memory image into the core file.
 186 This may lead to substantially larger core files than expected.
 187 .Pp
 188 It would be nice if
 189 .Xr lldb 1
 190 could examine extended core files directly i.e. without the conversion step.
 191 .Pp
 192 .Sh SEE ALSO
 193 .Xr dyld 1 ,
 194 .Xr update_dyld_shared_cache 1