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