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