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