1 PGRAB_CORE(3PROC) Process Control Library Functions PGRAB_CORE(3PROC) 2 3 NAME 4 Pgrab_core, Pfgrab_core - grab a core file 5 6 LIBRARY 7 Process Control Library (libproc, -lproc) 8 9 SYNOPSIS 10 #include <libproc.h> 11 12 struct ps_prochandle * 13 Pgrab_core(const char *core, const char *aout, int gflag, int *perr); 14 15 struct ps_prochandle * 16 Pfgrab_core(int core_fd, const char *aout, int *perr); 17 18 DESCRIPTION 19 The Pgrab_core() and Pfgrab_core() functions open a core file for 20 introspection. Unlike live processes, core files cannot have their state 21 modified; however, all of the functions that iterate or query state will 22 work. These functions work on all illumos core files and the core files 23 of some other operating systems. See both core(4) and the Core Files 24 section of libproc(3LIB) for more information. 25 26 The Pgrab_core() function attempts to open the core file specified by 27 core. The system attempts to determine the path of the original 28 executable. The argument aout may either be the path to that file, a 29 path to a directory to search, or the NULL pointer, if neither is known. 30 The system will search for it and will supplement information in the core 31 file with that. 32 33 The gflag argument to the Pgrab_core() function controls how the file is 34 opened. If the PGRAB_RDONLY flag is specified, then the core file will 35 be opened with the open(2) flag O_RDONLY. Otherwise, it will be opened 36 O_RDWR. 37 38 The perr argument must be a non-NULL pointer which will store a more 39 detailed error in the event that the Pgrab_core() function fails. A 40 human-readable form of the error can be obtained through the routine 41 Pgrab_error(3PROC). 42 43 The Pfgrab_core() is similar to the Pgrab_core() function. Except, 44 instead of operating on a path, it opens a handle to the core file 45 referenced by core_fd. The aout and perr arguments are identical to 46 those in the Pgrab_core() function. 47 48 The handle returned, from either function, is valid until it is closed 49 with Prelease(3PROC) or Pfree(3PROC). 50 51 RETURN VALUES 52 Upon successful completion, the Pgrab_core() and Pfgrab_core() functions 53 return a libproc handle to the core file. Otherwise, NULL is returned 54 and perr is filled in with a more detailed error message. 55 56 ERRORS 57 The Pgrab_core() function will fail if: 58 59 G_NOCORE The file core does not exist. 60 61 G_STRANGE An unexpected system error occurred while trying to 62 open core. The value of errno indicates the system 63 failure. 64 65 The Pgrab_core() and Pfgrab_core() functions will fail if: 66 67 G_ELF An unexpected libelf(3LIB) failure occurred. 68 69 G_FORMAT The core file referred to by either core or core_fd is 70 not a valid ELF core file. 71 72 G_ISAINVAL The architecture of the core file referred to by 73 either core or core_fd does not match the current 74 running system. 75 76 G_LP64 The calling process is a 32-bit process and the core 77 file referenced by either core or core_fd refers to a 78 64-bit process. 79 80 G_NOTE The ELF notes present in the core file referred to by 81 either core or core_fd are corrupt or missing required 82 data. 83 84 G_STRANGE An unanticipated system error occurred while trying to 85 open the core file and create the handle. The value 86 of errno indicates the system failure. 87 88 INTERFACE STABILITY 89 Uncommitted 90 91 MT-LEVEL 92 MT-Safe 93 94 SEE ALSO 95 gcore(1), open(2), errno(3C), libproc(3LIB), Pfree(3PROC), 96 Pgrab_error(3PROC), Prelease(3PROC), core(4) 97 98 illumos May 11, 2016 illumos