]> git.saurik.com Git - apple/system_cmds.git/blob - gcore.tproj/gcore.1
system_cmds-735.20.1.tar.gz
[apple/system_cmds.git] / gcore.tproj / gcore.1
1 .Dd 2/10/16
2 .Dt gcore 1
3 .Os Darwin
4 .Sh NAME
5 .Nm gcore
6 .Nd get core images of running processes
7 .Sh SYNOPSIS
8 .Nm
9 .Op Fl s
10 .Op Fl v
11 .Op Fl b Ar size
12 .Op Fl o Ar path | Fl c Ar pathformat
13 .Ar pid
14 .Sh DESCRIPTION
15 The
16 .Nm gcore
17 program creates a core file image of the process specified by
18 .Ar pid .
19 The resulting core file can be used with a debugger, e.g.
20 .Xr lldb(1) ,
21 to examine the state of the process.
22 .Pp
23 The following options are available:
24 .Bl -tag -width Fl
25 .It Fl s
26 Suspend the process while the core file is captured.
27 .It Fl v
28 Report progress on the dump as it proceeds.
29 .It Fl b Ar size
30 Limit the size of the core file to
31 .Ar size
32 MiBytes.
33 .El
34 .Pp
35 The following options control the name of the core file:
36 .Bl -tag -width flag
37 .It Fl o Ar path
38 Write the core file to
39 .Ar path .
40 .It Fl c Ar pathformat
41 Write the core file to
42 .Ar pathformat .
43 The
44 .Ar pathformat
45 string is treated as a pathname that may contain various special
46 characters which cause the interpolation of strings representing
47 specific attributes of the process into the name.
48 .Pp
49 Each special character is introduced by the
50 .Cm %
51 character. The format characters and their meanings are:
52 .Bl -tag -width Fl
53 .It Cm N
54 The name of the program being dumped, as reported by
55 .Xr ps 1 .
56 .It Cm U
57 The uid of the process being dumped, converted to a string.
58 .It Cm P
59 The pid of the process being dumped, converted to a string.
60 .It Cm T
61 The time when the core file was taken, converted to ISO 8601 format.
62 .It Cm %
63 Output a percent character.
64 .El
65 .El
66 .Pp
67 The default file name used by
68 .Nm gcore
69 is
70 .Ar %N-%P-%T .
71 By default, the core file will be written to a directory whose
72 name is determined from the
73 .Ar kern.corefile
74 MIB. This can be printed or modified using
75 .Xr sysctl 8 .
76 .Pp
77 The directory where the core file is to be written must be
78 accessible to the owner of the target process.
79 .Pp
80 .Nm gcore
81 will not overwrite an existing file,
82 nor will it create missing directories in the path.
83 .Sh EXIT_STATUS
84 .Ex -std
85 .Pp
86 .Sh FILES
87 .Bl -tag -width "/cores/%N-%P-%T plus" -compact
88 .It Pa /cores/%N-%P-%T
89 default pathname for the corefile.
90 .El
91 .Sh BUGS
92 With the
93 .Fl b
94 flag,
95 .Nm gcore
96 writes out as much data as it can up to the specified limit,
97 even if that results in an incomplete core image.
98 Such a partial core dump may confuse subsequent
99 programs that attempt to parse the contents of such files.
100 .Sh SEE ALSO
101 .Xr lldb 1 ,
102 .Xr core 5 ,
103 .Xr Mach-O 5 ,
104 .Xr sysctl 8 ,
105 .Xr sudo 8 .