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_FILE 3PROC 16.Os 17.Sh NAME 18.Nm Pgrab_file 19.Nd grab and inspect an ELF object 20.Sh SYNOPSIS 21.Lb libproc 22.In libproc.h 23.Ft struct ps_prochandle 24.Fo Pgrab_file 25.Fa "const char *fname" 26.Fa "int *perr" 27.Fc 28.Sh DESCRIPTION 29The 30.Fn Pgrab_file 31function creates a handle to the ELF object contained in file 32.Fa fname . 33This handle is considered an 34.Em idle 35handle, it allows one to inspect aspects of the ELF contents present in 36the handle, for example obtaining CTF information and looking up 37symbols. 38.Pp 39There is no running state associated with this handle nor can 40there be. If one intends to control a running process or create a 41process, see 42.Xr Pgrab 3PROC 43and 44.Xr Pcreate 3PROC 45respectively. To inspect a core file use 46.Xr Pgrab_core 3PROC . 47.Pp 48The 49.Fa perr 50argument must be a 51.Pf non- Dv NULL 52pointer which will store a more detailed error in the event that 53.Fn Pgrab_file 54fails. A human-readable form of the error can be obtained with 55.Xr Pgrab_error 3PROC . 56.Pp 57When finished with the returned handle, 58.Xr Prelease 3PROC 59must be called to clean up resources associated with it. 60.Sh RETURN VALUES 61Upon successful completion, the 62.Fn Pgrab_file 63function returns a control handle to the process. Otherwise, 64.Dv NULL 65is returned and 66.Fa perr 67is filled in with an error code. 68.Sh ERRORS 69.Bl -tag -width Er -offset indent 70.It Er G_ELF 71An unexpected 72.Xr libelf 3LIB 73failure occurred while processing the file named by 74.Fa fname . 75.It Er G_FORMAT 76The file named by 77.Fa fname 78is not a valid ELF file. 79.It Er G_NOEXEC 80The file named by 81.Fa fname 82does not exist. 83.It Er G_STRANGE 84An unanticipated system error occurred while trying to grab the 85file 86.Fa fname 87and create the handle. 88The value of 89.Sy errno 90indicates the system failure. 91.El 92.Sh INTERFACE STABILITY 93.Sy Uncommitted 94.Sh MT-LEVEL 95.Sy MT-Safe 96.Sh SEE ALSO 97.Xr errno 3C , 98.Xr libelf 3LIB , 99.Xr libproc 3LIB , 100.Xr Pfree 3PROC , 101.Xr Pgrab_core 3PROC , 102.Xr Pgrab_error 3PROC , 103.Xr Pgrab_file 3PROC , 104.Xr Prelease 3PROC 105