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