1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" 14.Dd May 11, 2016 15.Dt PGRAB_CORE 3PROC 16.Os 17.Sh NAME 18.Nm Pgrab_core , 19.Nm Pfgrab_core 20.Nd grab a core file 21.Sh LIBRARY 22.Lb libproc 23.Sh SYNOPSIS 24.In libproc.h 25.Ft "struct ps_prochandle *" 26.Fo Pgrab_core 27.Fa "const char *core" 28.Fa "const char *aout" 29.Fa "int gflag" 30.Fa "int *perr" 31.Fc 32.Ft "struct ps_prochandle *" 33.Fo Pfgrab_core 34.Fa "int core_fd" 35.Fa "const char *aout" 36.Fa "int *perr" 37.Fc 38.Sh DESCRIPTION 39The 40.Fn Pgrab_core 41and 42.Fn Pfgrab_core 43functions open a core file for introspection. 44Unlike live processes, core files cannot have their state modified; 45however, all of the functions that iterate or query state will work. 46These functions work on all illumos core files and the core files of some other 47operating systems. 48See both 49.Xr core 4 50and the 51.Em Core Files 52section of 53.Xr libproc 3LIB 54for more information. 55.Pp 56The 57.Fn Pgrab_core 58function attempts to open the core file specified by 59.Fa core . 60The system attempts to determine the path of the original executable. 61The argument 62.Fa aout 63may either be the path to that file, a path to a directory to search, or the 64.Dv NULL 65pointer, if neither is known. 66The system will search for it and will supplement information in the core file 67with that. 68.Pp 69The 70.Fa gflag 71argument to the 72.Fn Pgrab_core 73function controls how the file is opened. 74If the 75.Dv PGRAB_RDONLY 76flag is specified, then the core file will be opened with the 77.Xr open 2 78flag 79.Dv O_RDONLY . 80Otherwise, it will be opened 81.Dv O_RDWR . 82.Pp 83The 84.Fa perr 85argument must be a 86.Pf non- Dv NULL 87pointer which will store a more detailed error in the event that the 88.Fn Pgrab_core 89function fails. 90A human-readable form of the error can be obtained through the routine 91.Xr Pgrab_error 3PROC . 92.Pp 93The 94.Fn Pfgrab_core 95is similar to the 96.Fn Pgrab_core 97function. 98Except, instead of operating on a path, it opens a handle to the core file 99referenced by 100.Fa core_fd . 101The 102.Fa aout 103and 104.Fa perr 105arguments are identical to those in the 106.Fn Pgrab_core 107function. 108.Pp 109The handle returned, from either function, is valid until it is closed 110with 111.Xr Prelease 3PROC 112or 113.Xr Pfree 3PROC . 114.Sh RETURN VALUES 115Upon successful completion, the 116.Fn Pgrab_core 117and 118.Fn Pfgrab_core 119functions return a 120.Sy libproc 121handle to the core file. 122Otherwise, 123.Dv NULL 124is returned and 125.Fa perr 126is filled in with a more detailed error message. 127.Sh ERRORS 128The 129.Fn Pgrab_core 130function will fail if: 131.Bl -tag -width Er 132.It Er G_NOCORE 133The file 134.Fa core 135does not exist. 136.It Er G_STRANGE 137An unexpected system error occurred while trying to open 138.Fa core . 139The value of 140.Sy errno 141indicates the system failure. 142.El 143.Pp 144The 145.Fn Pgrab_core 146and 147.Fn Pfgrab_core 148functions will fail if: 149.Bl -tag -width Er 150.It Dv G_ELF 151An unexpected 152.Xr libelf 3LIB 153failure occurred. 154.It Dv G_FORMAT 155The core file referred to by either 156.Fa core 157or 158.Fa core_fd 159is not a valid ELF core file. 160.It Dv G_ISAINVAL 161The architecture of the core file referred to by either 162.Fa core 163or 164.Fa core_fd 165does not match the current running system. 166.It Dv G_LP64 167The calling process is a 32-bit process and the core file referenced by 168either 169.Fa core 170or 171.Fa core_fd 172refers to a 64-bit process. 173.It Dv G_NOTE 174The ELF notes present in the core file referred to by either 175.Fa core 176or 177.Fa core_fd 178are corrupt or missing required data. 179.It Dv G_STRANGE 180An unanticipated system error occurred while trying to open the core 181file and create the handle. 182The value of 183.Sy errno 184indicates the system failure. 185.El 186.Sh INTERFACE STABILITY 187.Sy Uncommitted 188.Sh MT-LEVEL 189.Sy MT-Safe 190.Sh SEE ALSO 191.Xr gcore 1 , 192.Xr open 2 , 193.Xr errno 3C , 194.Xr libproc 3LIB , 195.Xr Pfree 3PROC , 196.Xr Pgrab_error 3PROC , 197.Xr Prelease 3PROC , 198.Xr core 4 199