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