Print this page
Code review comments from jeffpc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man4/core.4.man.txt
+++ new/usr/src/man/man4/core.4.man.txt
1 1 CORE(4) File Formats and Configurations CORE(4)
2 2
3 3
4 4
5 5 NAME
6 6 core - process core file
7 7
8 8 DESCRIPTION
9 9 The operating system writes out a core file for a process when the
10 10 process is terminated due to receiving certain signals. A core file is
11 11 a disk copy of the contents of the process address space at the time
12 12 the process received the signal, along with additional information
13 13 about the state of the process. This information can be consumed by a
14 14 debugger. Core files can also be generated by applying the gcore(1)
15 15 utility to a running process.
16 16
17 17
18 18 Typically, core files are produced following abnormal termination of a
19 19 process resulting from a bug in the corresponding application. Whatever
20 20 the cause, the core file itself provides invaluable information to the
21 21 programmer or support engineer to aid in diagnosing the problem. The
22 22 core file can be inspected using a debugger such as dbx(1) or mdb(1) or
23 23 by applying one of the proc(1) tools.
24 24
25 25
26 26 The operating system attempts to create up to two core files for each
27 27 abnormally terminating process, using a global core file name pattern
28 28 and a per-process core file name pattern. These patterns are expanded
29 29 to determine the pathname of the resulting core files, and can be
30 30 configured by coreadm(1M). By default, the global core file pattern is
31 31 disabled and not used, and the per-process core file pattern is set to
32 32 core. Therefore, by default, the operating system attempts to create a
33 33 core file named core in the process's current working directory.
34 34
35 35
36 36 A process terminates and produces a core file whenever it receives one
37 37 of the signals whose default disposition is to cause a core dump. The
38 38 list of signals that result in generating a core file is shown in
39 39 signal.h(3HEAD). Therefore, a process might not produce a core file if
40 40 it has blocked or modified the behavior of the corresponding signal.
41 41 Additionally, no core dump can be created under the following
42 42 conditions:
43 43
44 44 o If normal file and directory access permissions prevent the
45 45 creation or modification of the per-process core file
46 46 pathname by the current process user and group ID. This test
47 47 does not apply to the global core file pathname because,
48 48 regardless of the UID of the process dumping core, the
49 49 attempt to write the global core file is made as the
50 50 superuser.
51 51
52 52 o Core files owned by the user nobody will not be produced.
53 53 For example, core files generated for the superuser on an
54 54 NFS directory are owned by nobody and are, therefore, not
55 55 written.
56 56
57 57 o If the core file pattern expands to a pathname that contains
58 58 intermediate directory components that do not exist. For
59 59 example, if the global pattern is set to
60 60 /var/core/%n/core.%p, and no directory /var/core/`uname -n`
61 61 has been created, no global core files are produced.
62 62
63 63 o If the destination directory is part of a filesystem that is
64 64 mounted read-only.
65 65
66 66 o If the resource limit RLIMIT_CORE has been set to 0 for the
67 67 process, no per-process core file is produced. Refer to
68 68 setrlimit(2) and ulimit(1) for more information on resource
69 69 limits.
70 70
71 71 o If the core file name already exists in the destination
72 72 directory and is not a regular file (that is, is a symlink,
73 73 block or character special-file, and so forth).
74 74
75 75 o If the kernel cannot open the destination file O_EXCL, which
76 76 can occur if same file is being created by another process
77 77 simultaneously.
78 78
79 79 o If the process's effective user ID is different from its
80 80 real user ID or if its effective group ID is different from
81 81 its real group ID. Similarly, set-user-ID and set-group-ID
82 82 programs do not produce core files as this could potentially
83 83 compromise system security. These processes can be
84 84 explicitly granted permission to produce core files using
85 85 coreadm(1M), at the risk of exposing secure information.
86 86
87 87
88 88 The core file contains all the process information pertinent to
89 89 debugging: contents of hardware registers, process status, and process
90 90 data. The format of a core file is object file specific.
91 91
92 92
93 93 For ELF executable programs (see a.out(4)), the core file generated is
94 94 also an ELF file, containing ELF program and file headers. The e_type
95 95 field in the file header has type ET_CORE. The program header contains
96 96 an entry for every segment that was part of the process address space,
97 97 including shared library segments. The contents of the mappings
98 98 specified by coreadm(1M) are also part of the core image. Each program
99 99 header has its p_memsz field set to the size of the mapping. The
100 100 program headers that represent mappings whose data is included in the
101 101 core file have their p_filesz field set the same as p_memsz, otherwise
102 102 p_filesz is zero.
103 103
104 104
105 105 A mapping's data can be excluded due to the core file content settings
106 106 (see coreadm(1M)), due to a failure, or due to a signal received after
107 107 core dump initiation but before its completion. If the data is excluded
108 108 because of a failure, the program header entry will have the
109 109 PF_SUNW_FAILURE flag set in its p_flags field; if the data is excluded
110 110 because of a signal, the segment's p_flags field will have the
111 111 PF_SUNW_KILLED flag set.
112 112
113 113
114 114 The program headers of an ELF core file also contain entries for two
115 115 NOTE segments, each containing several note entries as described below.
116 116 The note entry header and core file note type (n_type) definitions are
117 117 contained in <sys/elf.h>. The first NOTE segment exists for binary
118 118 compatibility with old programs that deal with core files. It contains
119 119 structures defined in <sys/old_procfs.h>. New programs should recognize
120 120 and skip this NOTE segment, advancing instead to the new NOTE segment.
121 121 The old NOTE segment is deleted from core files in a future release.
122 122
123 123
124 124 The old NOTE segment contains the following entries. Each has entry
125 125 name "CORE" and presents the contents of a system structure:
126 126
127 127 prpsinfo_t
128 128 n_type: NT_PRPSINFO. This entry contains information of
129 129 interest to the ps(1) command, such as process status,
130 130 CPU usage, nice value, controlling terminal, user-ID,
131 131 process-ID, the name of the executable, and so forth.
132 132 The prpsinfo_t structure is defined in
133 133 <sys/old_procfs.h>.
134 134
135 135
136 136 char array
137 137 n_type: NT_PLATFORM. This entry contains a string
138 138 describing the specific model of the hardware platform
139 139 on which this core file was created. This information
140 140 is the same as provided by sysinfo(2) when invoked with
141 141 the command SI_PLATFORM.
142 142
143 143
144 144 auxv_t array
145 145 n_type: NT_AUXV. This entry contains the array of
146 146 auxv_t structures that was passed by the operating
147 147 system as startup information to the dynamic linker.
148 148 Auxiliary vector information is defined in
149 149 <sys/auxv.h>.
150 150
151 151
152 152
153 153 Following these entries, for each active (non-zombie) light-weight
154 154 process (LWP) in the process, the old NOTE segment contains an entry
155 155 with a prstatus_t structure, plus other optionally-present entries
156 156 describing the LWP, as follows:
157 157
158 158 prstatus_t
159 159 n_type: NT_PRSTATUS. This structure contains things of
160 160 interest to a debugger from the operating system, such
161 161 as the general registers, signal dispositions, state,
162 162 reason for stopping, process-ID, and so forth. The
163 163 prstatus_t structure is defined in <sys/old_procfs.h>.
164 164
165 165
166 166 prfpregset_t
167 167 n_type: NT_PRFPREG. This entry is present only if the
168 168 LWP used the floating-point hardware. It contains the
169 169 floating-point registers. The prfpregset_t structure is
170 170 defined in <sys/procfs_isa.h>.
171 171
172 172
173 173 gwindows_t
174 174 n_type: NT_GWINDOWS. This entry is present only on a
175 175 SPARC machine and only if the system was unable to
176 176 flush all of the register windows to the stack. It
177 177 contains all of the unspilled register windows. The
178 178 gwindows_t structure is defined in <sys/regset.h>.
179 179
180 180
181 181 prxregset_t
182 182 n_type: NT_PRXREG. This entry is present only if the
183 183 machine has extra register state associated with it. It
184 184 contains the extra register state. The prxregset_t
185 185 structure is defined in <sys/procfs_isa.h>.
186 186
187 187
188 188
189 189 The new NOTE segment contains the following entries. Each has entry
190 190 name "CORE" and presents the contents of a system structure:
191 191
192 192 psinfo_t
193 193 n_type: NT_PSINFO. This structure contains
194 194 information of interest to the ps(1) command, such
195 195 as process status, CPU usage, nice value,
196 196 controlling terminal, user-ID, process-ID, the name
197 197 of the executable, and so forth. The psinfo_t
198 198 structure is defined in <sys/procfs.h>.
199 199
200 200
201 201 pstatus_t
202 202 n_type: NT_PSTATUS. This structure contains things
203 203 of interest to a debugger from the operating
204 204 system, such as pending signals, state, process-ID,
205 205 and so forth. The pstatus_t structure is defined in
206 206 <sys/procfs.h>.
207 207
208 208
209 209 char array
210 210 n_type: NT_PLATFORM. This entry contains a string
211 211 describing the specific model of the hardware
212 212 platform on which this core file was created. This
213 213 information is the same as provided by sysinfo(2)
214 214 when invoked with the command SI_PLATFORM.
215 215
216 216
217 217 auxv_t array
218 218 n_type: NT_AUXV. This entry contains the array of
219 219 auxv_t structures that was passed by the operating
220 220 system as startup information to the dynamic
221 221 linker. Auxiliary vector information is defined in
222 222 <sys/auxv.h>.
223 223
224 224
225 225 struct utsname
226 226 n_type: NT_UTSNAME. This structure contains the
227 227 system information that would have been returned to
228 228 the process if it had performed a uname(2) system
229 229 call prior to dumping core. The utsname structure
230 230 is defined in <sys/utsname.h>.
231 231
232 232
233 233 prcred_t
234 234 n_type: NT_PRCRED. This structure contains the
235 235 process credentials, including the real, saved, and
236 236 effective user and group IDs. The prcred_t
237 237 structure is defined in <sys/procfs.h>. Following
238 238 the structure is an optional array of supplementary
239 239 group IDs. The total number of supplementary group
240 240 IDs is given by the pr_ngroups member of the
241 241 prcred_t structure, and the structure includes
242 242 space for one supplementary group. If pr_ngroups is
243 243 greater than 1, there is pr_ngroups - 1 gid_t items
244 244 following the structure; otherwise, there is no
245 245 additional data.
246 246
247 247
248 248 char array
249 249 n_type: NT_ZONENAME. This entry contains a string
250 250 which describes the name of the zone in which the
251 251 process was running. See zones(5). The information
252 252 is the same as provided by getzonenamebyid(3C) when
253 253 invoked with the numerical ID returned by
254 254 getzoneid(3C).
255 255
256 256
257 257 prfdinfo_t
258 258 n_type: NT_FDINFO. This structure contains
259 259 information about any open file descriptors,
260 260 including the path, flags, and stat(2) information.
261 261 The prfdinfo_t structure is defined in
262 262 <sys/procfs.h>.
263 263
264 264
265 265 struct ssd array
266 266 n_type: NT_LDT. This entry is present only on an
267 267 32-bit x86 machine and only if the process has set
268 268 up a Local Descriptor Table (LDT). It contains an
269 269 array of structures of type struct ssd, each of
270 270 which was typically used to set up the %gs segment
271 271 register to be used to fetch the address of the
272 272 current thread information structure in a
273 273 multithreaded process. The ssd structure is defined
274 274 in <sys/sysi86.h>.
275 275
276 276
277 277 core_content_t
278 278 n_type: NT_CONTENT. This optional entry indicates
279 279 which parts of the process image are specified to
280 280 be included in the core file. See coreadm(1M).
281 281
282 282
283 283
284 284 Following these entries, for each active and zombie LWP in the process,
285 285 the new NOTE segment contains an entry with an lwpsinfo_t structure
286 286 plus, for a non-zombie LWP, an entry with an lwpstatus_t structure,
287 287 plus other optionally-present entries describing the LWP, as follows. A
288 288 zombie LWP is a non-detached LWP that has terminated but has not yet
289 289 been reaped by another LWP in the same process.
290 290
291 291 lwpsinfo_t
292 292 n_type: NT_LWPSINFO. This structure contains information
293 293 of interest to the ps(1) command, such as LWP status,
294 294 CPU usage, nice value, LWP-ID, and so forth. The
295 295 lwpsinfo_t structure is defined in <sys/procfs.h>. This
296 296 is the only entry present for a zombie LWP.
297 297
298 298
299 299 lwpstatus_t
300 300 n_type: NT_LWPSTATUS. This structure contains things of
301 301 interest to a debugger from the operating system, such
302 302 as the general registers, the floating point registers,
303 303 state, reason for stopping, LWP-ID, and so forth. The
304 304 lwpstatus_t structure is defined in <sys/procfs.h>>.
305 305
306 306
307 307 gwindows_t
308 308 n_type: NT_GWINDOWS. This entry is present only on a
309 309 SPARC machine and only if the system was unable to flush
310 310 all of the register windows to the stack. It contains
311 311 all of the unspilled register windows. The gwindows_t
312 312 structure is defined in <sys/regset.h>.
313 313
314 314
315 315 prxregset_t
316 316 n_type: NT_PRXREG. This entry is present only if the
317 317 machine has extra register state associated with it. It
318 318 contains the extra register state. The prxregset_t
319 319 structure is defined in <sys/procfs_isa.h>.
320 320
321 321
322 322 asrset_t
323 323 n_type: NT_ASRS. This entry is present only on a SPARC
324 324 V9 machine and only if the process is a 64-bit process.
325 325 It contains the ancillary state registers for the LWP.
326 326 The asrset_t structure is defined in <sys/regset.h>.
327 327
328 328
329 329 psinfo_t
330 330 n_type: NT_SPYMASTER. This entry is present only for an
331 331 agent LWP and contains the psinfo_t of the process that
332 332 created the agent LWP. See the proc(4) description of
333 333 the spymaster entry for more details.
334 334
335 335
336 336 prsecflags_t
337 337 n_type: NT_SECFLAGS. This entry contains the process
338 338 security-flags, see security-flags(5), proc(4), and
339 339 psecflags(1M) for more information.
340 340
341 341
342 342
343 343 Depending on the coreadm(1M) settings, the section header of an ELF
344 344 core file can contain entries for CTF, symbol table, and string table
345 345 sections. The sh_addr fields are set to the base address of the first
346 346 mapping of the load object that they came from to. This can be used to
347 347 match those sections with the corresponding load object.
348 348
349 349
350 350 The size of the core file created by a process can be controlled by the
351 351 user (see getrlimit(2)).
352 352
353 353 SEE ALSO
|
↓ open down ↓ |
353 lines elided |
↑ open up ↑ |
354 354 elfdump(1), gcore(1), mdb(1), proc(1), ps(1), coreadm(1M),
355 355 getrlimit(2), setrlimit(2), setuid(2), sysinfo(2), uname(2),
356 356 getzonenamebyid(3C), getzoneid(3C), elf(3ELF), signal.h(3HEAD),
357 357 a.out(4), proc(4), zones(5), security-flags(5)
358 358
359 359
360 360 ANSI C Programmer's Guide
361 361
362 362
363 363
364 - July 23, 2015 CORE(4)
364 + June 6, 2016 CORE(4)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX