Print this page
Code review comments from jeffpc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man4/core.4
+++ new/usr/src/man/man4/core.4
1 1 '\" te
2 2 .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" Copyright 2012 DEY Storage Systems, Inc. All rights reserved.
4 4 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
5 5 .\" Copyright 1989 AT&T
6 6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
7 7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
8 8 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
9 -.TH CORE 4 "Jul 23, 2015"
9 +.TH CORE 4 "Jun 6, 2016"
10 10 .SH NAME
11 11 core \- process core file
12 12 .SH DESCRIPTION
13 13 .LP
14 14 The operating system writes out a core file for a process when the process is
15 15 terminated due to receiving certain signals. A core file is a disk copy of the
16 16 contents of the process address space at the time the process received the
17 17 signal, along with additional information about the state of the process. This
18 18 information can be consumed by a debugger. Core files can also be generated by
19 19 applying the \fBgcore\fR(1) utility to a running process.
20 20 .sp
21 21 .LP
22 22 Typically, core files are produced following abnormal termination of a process
23 23 resulting from a bug in the corresponding application. Whatever the cause, the
24 24 core file itself provides invaluable information to the programmer or support
25 25 engineer to aid in diagnosing the problem. The core file can be inspected using
26 26 a debugger such as \fBdbx\fR(1) or \fBmdb\fR(1) or by applying one of the
27 27 \fBproc\fR(1) tools.
28 28 .sp
29 29 .LP
30 30 The operating system attempts to create up to two core files for each
31 31 abnormally terminating process, using a global core file name pattern and a
32 32 per-process core file name pattern. These patterns are expanded to determine
33 33 the pathname of the resulting core files, and can be configured by
34 34 \fBcoreadm\fR(1M). By default, the global core file pattern is disabled and not
35 35 used, and the per-process core file pattern is set to \fBcore\fR. Therefore, by
36 36 default, the operating system attempts to create a core file named \fBcore\fR
37 37 in the process's current working directory.
38 38 .sp
39 39 .LP
40 40 A process terminates and produces a core file whenever it receives one of the
41 41 signals whose default disposition is to cause a core dump. The list of signals
42 42 that result in generating a core file is shown in \fBsignal.h\fR(3HEAD).
43 43 Therefore, a process might not produce a core file if it has blocked or
44 44 modified the behavior of the corresponding signal. Additionally, no core dump
45 45 can be created under the following conditions:
46 46 .RS +4
47 47 .TP
48 48 .ie t \(bu
49 49 .el o
50 50 If normal file and directory access permissions prevent the creation or
51 51 modification of the per-process core file pathname by the current process user
52 52 and group ID. This test does not apply to the global core file pathname
53 53 because, regardless of the UID of the process dumping core, the attempt to
54 54 write the global core file is made as the superuser.
55 55 .RE
56 56 .RS +4
57 57 .TP
58 58 .ie t \(bu
59 59 .el o
60 60 Core files owned by the user \fBnobody\fR will not be produced. For example,
61 61 core files generated for the superuser on an NFS directory are owned by
62 62 \fBnobody\fR and are, therefore, not written.
63 63 .RE
64 64 .RS +4
65 65 .TP
66 66 .ie t \(bu
67 67 .el o
68 68 If the core file pattern expands to a pathname that contains intermediate
69 69 directory components that do not exist. For example, if the global pattern is
70 70 set to \fB/var/core/%n/core.%p\fR, and no directory \fB/var/core/`uname -n`\fR
71 71 has been created, no global core files are produced.
72 72 .RE
73 73 .RS +4
74 74 .TP
75 75 .ie t \(bu
76 76 .el o
77 77 If the destination directory is part of a filesystem that is mounted read-only.
78 78 .RE
79 79 .RS +4
80 80 .TP
81 81 .ie t \(bu
82 82 .el o
83 83 If the resource limit \fBRLIMIT_CORE\fR has been set to \fB0\fR for the
84 84 process, no per-process core file is produced. Refer to \fBsetrlimit\fR(2) and
85 85 \fBulimit\fR(1) for more information on resource limits.
86 86 .RE
87 87 .RS +4
88 88 .TP
89 89 .ie t \(bu
90 90 .el o
91 91 If the core file name already exists in the destination directory and is not a
92 92 regular file (that is, is a symlink, block or character special-file, and so
93 93 forth).
94 94 .RE
95 95 .RS +4
96 96 .TP
97 97 .ie t \(bu
98 98 .el o
99 99 If the kernel cannot open the destination file \fBO_EXCL\fR, which can occur if
100 100 same file is being created by another process simultaneously.
101 101 .RE
102 102 .RS +4
103 103 .TP
104 104 .ie t \(bu
105 105 .el o
106 106 If the process's effective user ID is different from its real user ID or if its
107 107 effective group ID is different from its real group ID. Similarly, set-user-ID
108 108 and set-group-ID programs do not produce core files as this could potentially
109 109 compromise system security. These processes can be explicitly granted
110 110 permission to produce core files using \fBcoreadm\fR(1M), at the risk of
111 111 exposing secure information.
112 112 .RE
113 113 .sp
114 114 .LP
115 115 The core file contains all the process information pertinent to debugging:
116 116 contents of hardware registers, process status, and process data. The format of
117 117 a core file is object file specific.
118 118 .sp
119 119 .LP
120 120 For ELF executable programs (see \fBa.out\fR(4)), the core file generated is
121 121 also an ELF file, containing ELF program and file headers. The \fBe_type\fR
122 122 field in the file header has type \fBET_CORE\fR. The program header contains an
123 123 entry for every segment that was part of the process address space, including
124 124 shared library segments. The contents of the mappings specified by
125 125 \fBcoreadm\fR(1M) are also part of the core image. Each program header has its
126 126 \fBp_memsz\fR field set to the size of the mapping. The program headers that
127 127 represent mappings whose data is included in the core file have their
128 128 \fBp_filesz\fR field set the same as \fBp_memsz\fR, otherwise \fBp_filesz\fR is
129 129 \fBzero\fR.
130 130 .sp
131 131 .LP
132 132 A mapping's data can be excluded due to the core file content settings (see
133 133 \fBcoreadm\fR(1M)), due to a failure, or due to a signal received after
134 134 core dump initiation but before its completion. If the data is excluded
135 135 because of a failure, the program header entry will have the
136 136 \fBPF_SUNW_FAILURE\fR flag
137 137 set in its \fBp_flags\fR field; if the data is excluded because of a signal,
138 138 the segment's \fBp_flags\fR field will have the \fBPF_SUNW_KILLED\fR
139 139 flag set.
140 140 .sp
141 141 .LP
142 142 The program headers of an \fBELF\fR core file also contain entries for two
143 143 \fBNOTE\fR segments, each containing several note entries as described below.
144 144 The note entry header and core file note type (\fBn_type\fR) definitions are
145 145 contained in <\fBsys/elf.h\fR>. The first \fBNOTE\fR segment exists for binary
146 146 compatibility with old programs that deal with core files. It contains
147 147 structures defined in <\fBsys/old_procfs.h\fR>. New programs should recognize
148 148 and skip this \fBNOTE\fR segment, advancing instead to the new \fBNOTE\fR
149 149 segment. The old \fBNOTE\fR segment is deleted from core files in a future
150 150 release.
151 151 .sp
152 152 .LP
153 153 The old \fBNOTE\fR segment contains the following entries. Each has entry name
154 154 \fB"CORE"\fR and presents the contents of a system structure:
155 155 .sp
156 156 .ne 2
157 157 .na
158 158 \fB\fBprpsinfo_t\fR\fR
159 159 .ad
160 160 .RS 16n
161 161 \fBn_type\fR: \fBNT_PRPSINFO\fR. This entry contains information of interest to
162 162 the \fBps\fR(1) command, such as process status, \fBCPU\fR usage, \fBnice\fR
163 163 value, controlling terminal, user-ID, process-ID, the name of the executable,
164 164 and so forth. The \fBprpsinfo_t\fR structure is defined in
165 165 <\fBsys/old_procfs.h\fR>.
166 166 .RE
167 167
168 168 .sp
169 169 .ne 2
170 170 .na
171 171 \fB\fBchar\fR array\fR
172 172 .ad
173 173 .RS 16n
174 174 \fBn_type\fR: \fBNT_PLATFORM\fR. This entry contains a string describing the
175 175 specific model of the hardware platform on which this core file was created.
176 176 This information is the same as provided by \fBsysinfo\fR(2) when invoked with
177 177 the command \fBSI_PLATFORM\fR.
178 178 .RE
179 179
180 180 .sp
181 181 .ne 2
182 182 .na
183 183 \fB\fBauxv_t\fR array\fR
184 184 .ad
185 185 .RS 16n
186 186 \fBn_type\fR: \fBNT_AUXV\fR. This entry contains the array of \fBauxv_t\fR
187 187 structures that was passed by the operating system as startup information to
188 188 the dynamic linker. Auxiliary vector information is defined in
189 189 <\fBsys/auxv.h\fR>.
190 190 .RE
191 191
192 192 .sp
193 193 .LP
194 194 Following these entries, for each active (non-zombie) light-weight process
195 195 (LWP) in the process, the old \fBNOTE\fR segment contains an entry with a
196 196 \fBprstatus_t\fR structure, plus other optionally-present entries describing
197 197 the LWP, as follows:
198 198 .sp
199 199 .ne 2
200 200 .na
201 201 \fB\fBprstatus_t\fR\fR
202 202 .ad
203 203 .RS 16n
204 204 \fBn_type\fR: \fBNT_PRSTATUS\fR. This structure contains things of interest to
205 205 a debugger from the operating system, such as the general registers, signal
206 206 dispositions, state, reason for stopping, process-ID, and so forth. The
207 207 \fBprstatus_t\fR structure is defined in <\fBsys/old_procfs.h\fR>.
208 208 .RE
209 209
210 210 .sp
211 211 .ne 2
212 212 .na
213 213 \fB\fBprfpregset_t\fR\fR
214 214 .ad
215 215 .RS 16n
216 216 \fBn_type\fR: \fBNT_PRFPREG\fR. This entry is present only if the \fBLWP\fR
217 217 used the floating-point hardware. It contains the floating-point registers. The
218 218 \fBprfpregset_t\fR structure is defined in <\fBsys/procfs_isa.h\fR>.
219 219 .RE
220 220
221 221 .sp
222 222 .ne 2
223 223 .na
224 224 \fB\fBgwindows_t\fR\fR
225 225 .ad
226 226 .RS 16n
227 227 \fBn_type\fR: \fBNT_GWINDOWS\fR. This entry is present only on a SPARC machine
228 228 and only if the system was unable to flush all of the register windows to the
229 229 stack. It contains all of the unspilled register windows. The \fBgwindows_t\fR
230 230 structure is defined in <\fBsys/regset.h\fR>.
231 231 .RE
232 232
233 233 .sp
234 234 .ne 2
235 235 .na
236 236 \fB\fBprxregset_t\fR\fR
237 237 .ad
238 238 .RS 16n
239 239 \fBn_type\fR: \fBNT_PRXREG\fR. This entry is present only if the machine has
240 240 extra register state associated with it. It contains the extra register state.
241 241 The \fBprxregset_t\fR structure is defined in <\fBsys/procfs_isa.h\fR>.
242 242 .RE
243 243
244 244 .sp
245 245 .LP
246 246 The new \fBNOTE\fR segment contains the following entries. Each has entry name
247 247 "\fBCORE\fR" and presents the contents of a system structure:
248 248 .sp
249 249 .ne 2
250 250 .na
251 251 \fB\fBpsinfo_t\fR\fR
252 252 .ad
253 253 .RS 20n
254 254 \fBn_type\fR: \fBNT_PSINFO\fR. This structure contains information of interest
255 255 to the \fBps\fR(1) command, such as process status, \fBCPU\fR usage, \fBnice\fR
256 256 value, controlling terminal, user-ID, process-ID, the name of the executable,
257 257 and so forth. The \fBpsinfo_t\fR structure is defined in <\fBsys/procfs.h\fR>.
258 258 .RE
259 259
260 260 .sp
261 261 .ne 2
262 262 .na
263 263 \fB\fBpstatus_t\fR\fR
264 264 .ad
265 265 .RS 20n
266 266 \fBn_type\fR: \fBNT_PSTATUS\fR. This structure contains things of interest to a
267 267 debugger from the operating system, such as pending signals, state, process-ID,
268 268 and so forth. The \fBpstatus_t\fR structure is defined in <\fBsys/procfs.h\fR>.
269 269 .RE
270 270
271 271 .sp
272 272 .ne 2
273 273 .na
274 274 \fB\fBchar\fR array\fR
275 275 .ad
276 276 .RS 20n
277 277 \fBn_type\fR: \fBNT_PLATFORM\fR. This entry contains a string describing the
278 278 specific model of the hardware platform on which this core file was created.
279 279 This information is the same as provided by \fBsysinfo\fR(2) when invoked with
280 280 the command \fBSI_PLATFORM\fR.
281 281 .RE
282 282
283 283 .sp
284 284 .ne 2
285 285 .na
286 286 \fB\fBauxv_t\fR array\fR
287 287 .ad
288 288 .RS 20n
289 289 \fBn_type\fR: \fBNT_AUXV\fR. This entry contains the array of \fBauxv_t\fR
290 290 structures that was passed by the operating system as startup information to
291 291 the dynamic linker. Auxiliary vector information is defined in
292 292 <\fBsys/auxv.h\fR>.
293 293 .RE
294 294
295 295 .sp
296 296 .ne 2
297 297 .na
298 298 \fB\fBstruct utsname\fR\fR
299 299 .ad
300 300 .RS 20n
301 301 \fBn_type\fR: \fBNT_UTSNAME\fR. This structure contains the system information
302 302 that would have been returned to the process if it had performed a
303 303 \fBuname\fR(2) system call prior to dumping core. The \fButsname\fR structure
304 304 is defined in <\fBsys/utsname.h\fR>.
305 305 .RE
306 306
307 307 .sp
308 308 .ne 2
309 309 .na
310 310 \fB\fBprcred_t\fR\fR
311 311 .ad
312 312 .RS 20n
313 313 \fBn_type\fR: \fBNT_PRCRED\fR. This structure contains the process credentials,
314 314 including the real, saved, and effective user and group IDs. The \fBprcred_t\fR
315 315 structure is defined in <\fBsys/procfs.h\fR>. Following the structure is an
316 316 optional array of supplementary group IDs. The total number of supplementary
317 317 group IDs is given by the \fBpr_ngroups\fR member of the \fBprcred_t\fR
318 318 structure, and the structure includes space for one supplementary group. If
319 319 \fBpr_ngroups\fR is greater than 1, there is \fBpr_ngroups - 1\fR \fBgid_t\fR
320 320 items following the structure; otherwise, there is no additional data.
321 321 .RE
322 322
323 323 .sp
324 324 .ne 2
325 325 .na
326 326 \fB\fBchar array\fR\fR
327 327 .ad
328 328 .RS 20n
329 329 \fBn_type\fR: \fBNT_ZONENAME\fR. This entry contains a string which describes
330 330 the name of the zone in which the process was running. See \fBzones\fR(5). The
331 331 information is the same as provided by \fBgetzonenamebyid\fR(3C) when invoked
332 332 with the numerical ID returned by \fBgetzoneid\fR(3C).
333 333 .RE
334 334
335 335 .sp
336 336 .ne 2
337 337 .na
338 338 \fB\fBprfdinfo_t\fR\fR
339 339 .ad
340 340 .RS 20n
341 341 \fBn_type\fR: \fBNT_FDINFO\fR. This structure contains information about
342 342 any open file descriptors, including the path, flags, and
343 343 \fBstat\fR(2) information. The \fBprfdinfo_t\fR structure is defined in
344 344 <\fBsys/procfs.h\fR>.
345 345 .RE
346 346
347 347 .sp
348 348 .ne 2
349 349 .na
350 350 \fB\fBstruct ssd\fR array\fR
351 351 .ad
352 352 .RS 20n
353 353 \fBn_type\fR: \fBNT_LDT\fR. This entry is present only on an 32-bit x86 machine
354 354 and only if the process has set up a Local Descriptor Table (LDT). It contains
355 355 an array of structures of type \fBstruct ssd\fR, each of which was typically
356 356 used to set up the \fB%gs\fR segment register to be used to fetch the address
357 357 of the current thread information structure in a multithreaded process. The
358 358 \fBssd\fR structure is defined in <\fBsys/sysi86.h\fR>.
359 359 .RE
360 360
361 361 .sp
362 362 .ne 2
363 363 .na
364 364 \fB\fBcore_content_t\fR\fR
365 365 .ad
366 366 .RS 20n
367 367 \fBn_type\fR: \fBNT_CONTENT\fR. This optional entry indicates which parts of
368 368 the process image are specified to be included in the core file. See
369 369 \fBcoreadm\fR(1M).
370 370 .RE
371 371
372 372 .sp
373 373 .LP
374 374 Following these entries, for each active and zombie \fBLWP\fR in the process,
375 375 the new \fBNOTE\fR segment contains an entry with an \fBlwpsinfo_t\fR structure
376 376 plus, for a non-zombie LWP, an entry with an \fBlwpstatus_t\fR structure, plus
377 377 other optionally-present entries describing the LWP, as follows. A zombie LWP
378 378 is a non-detached LWP that has terminated but has not yet been reaped by
379 379 another LWP in the same process.
380 380 .sp
381 381 .ne 2
382 382 .na
383 383 \fB\fBlwpsinfo_t\fR\fR
384 384 .ad
385 385 .RS 15n
386 386 \fBn_type\fR: \fBNT_LWPSINFO\fR. This structure contains information of
387 387 interest to the \fBps\fR(1) command, such as \fBLWP\fR status, \fBCPU\fR usage,
388 388 \fBnice\fR value, \fBLWP-ID\fR, and so forth. The \fBlwpsinfo_t\fR structure is
389 389 defined in <\fBsys/procfs.h\fR>. This is the only entry present for a zombie
390 390 LWP.
391 391 .RE
392 392
393 393 .sp
394 394 .ne 2
395 395 .na
396 396 \fB\fBlwpstatus_t\fR\fR
397 397 .ad
398 398 .RS 15n
399 399 \fBn_type\fR: \fBNT_LWPSTATUS\fR. This structure contains things of interest to
400 400 a debugger from the operating system, such as the general registers, the
401 401 floating point registers, state, reason for stopping, \fBLWP-ID\fR, and so
402 402 forth. The \fBlwpstatus_t\fR structure is defined in <\fBsys/procfs.h>\fR>.
403 403 .RE
404 404
405 405 .sp
406 406 .ne 2
407 407 .na
408 408 \fB\fBgwindows_t\fR\fR
409 409 .ad
410 410 .RS 15n
411 411 \fBn_type\fR: \fBNT_GWINDOWS\fR. This entry is present only on a SPARC machine
412 412 and only if the system was unable to flush all of the register windows to the
413 413 stack. It contains all of the unspilled register windows. The \fBgwindows_t\fR
414 414 structure is defined in \fB<sys/regset.h>\fR\&.
415 415 .RE
416 416
417 417 .sp
418 418 .ne 2
419 419 .na
420 420 \fB\fBprxregset_t\fR\fR
421 421 .ad
422 422 .RS 15n
423 423 \fBn_type\fR: \fBNT_PRXREG\fR. This entry is present only if the machine has
424 424 extra register state associated with it. It contains the extra register state.
425 425 The \fBprxregset_t\fR structure is defined in \fB<sys/procfs_isa.h>\fR\&.
426 426 .RE
427 427
428 428 .sp
429 429 .ne 2
430 430 .na
431 431 \fB\fBasrset_t\fR\fR
432 432 .ad
433 433 .RS 15n
434 434 \fBn_type\fR: \fBNT_ASRS\fR. This entry is present only on a SPARC V9 machine
435 435 and only if the process is a 64-bit process. It contains the ancillary state
436 436 registers for the \fBLWP.\fR The \fBasrset_t\fR structure is defined in
437 437 \fB<sys/regset.h>\fR\&.
438 438 .RE
439 439
440 440 .sp
441 441 .ne 2
442 442 .na
443 443 \fB\fBpsinfo_t\fR\fR
444 444 .ad
445 445 .RS 15n
446 446 \fBn_type\fR: \fBNT_SPYMASTER\fR. This entry is present only for an agent
447 447 LWP and contains the \fBpsinfo_t\fR of the process that created the agent
448 448 LWP. See the \fBproc\fR(4) description of the \fBspymaster\fR entry for
449 449 more details.
450 450 .RE
451 451
452 452 .sp
453 453 .ne 2
454 454 .na
455 455 \fB\fBprsecflags_t\fR\fR
456 456 .ad
457 457 .RS 15n
458 458 \fBn_type\fR: \fbNT_SECFLAGS\fR. This entry contains the process
459 459 security-flags, see \fBsecurity-flags\fR(5), \fBproc\fR(4), and
460 460 \fBpsecflags\fR(1M) for more information.
461 461 .RE
462 462
463 463 .sp
464 464 .LP
465 465 Depending on the \fBcoreadm\fR(1M) settings, the section header of an ELF core
466 466 file can contain entries for CTF, symbol table, and string table sections. The
467 467 \fBsh_addr\fR fields are set to the base address of the first mapping of the
468 468 load object that they came from to. This can be used to match those sections
469 469 with the corresponding load object.
470 470 .sp
471 471 .LP
472 472 The size of the core file created by a process can be controlled by the user
473 473 (see \fBgetrlimit\fR(2)).
474 474 .SH SEE ALSO
475 475 .LP
476 476 \fBelfdump\fR(1), \fBgcore\fR(1), \fBmdb\fR(1), \fBproc\fR(1), \fBps\fR(1),
477 477 \fBcoreadm\fR(1M), \fBgetrlimit\fR(2), \fBsetrlimit\fR(2), \fBsetuid\fR(2),
478 478 \fBsysinfo\fR(2), \fBuname\fR(2), \fBgetzonenamebyid\fR(3C),
479 479 \fBgetzoneid\fR(3C), \fBelf\fR(3ELF), \fBsignal.h\fR(3HEAD), \fBa.out\fR(4),
480 480 \fBproc\fR(4), \fBzones\fR(5), \fBsecurity-flags\fR(5)
481 481 .sp
482 482 .LP
483 483 \fIANSI C Programmer's Guide\fR
|
↓ open down ↓ |
464 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX