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 there be. 40If one intends to control a running process or create a process, see 41.Xr Pgrab 3PROC 42and 43.Xr Pcreate 3PROC 44respectively. 45To 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. 55A human-readable form of the error can be obtained with 56.Xr Pgrab_error 3PROC . 57.Pp 58When finished with the returned handle, 59.Xr Prelease 3PROC 60must be called to clean up resources associated with it. 61.Sh RETURN VALUES 62Upon successful completion, the 63.Fn Pgrab_file 64function returns a control handle to the process. 65Otherwise, 66.Dv NULL 67is returned and 68.Fa perr 69is filled in with an error code. 70.Sh ERRORS 71.Bl -tag -width Er -offset indent 72.It Er G_ELF 73An unexpected 74.Xr libelf 3LIB 75failure occurred while processing the file named by 76.Fa fname . 77.It Er G_FORMAT 78The file named by 79.Fa fname 80is not a valid ELF file. 81.It Er G_NOEXEC 82The file named by 83.Fa fname 84does not exist. 85.It Er G_STRANGE 86An unanticipated system error occurred while trying to grab the 87file 88.Fa fname 89and create the handle. 90The value of 91.Sy errno 92indicates the system failure. 93.El 94.Sh INTERFACE STABILITY 95.Sy Uncommitted 96.Sh MT-LEVEL 97.Sy MT-Safe 98.Sh SEE ALSO 99.Xr errno 3C , 100.Xr libelf 3LIB , 101.Xr libproc 3LIB , 102.Xr Pfree 3PROC , 103.Xr Pgrab_core 3PROC , 104.Xr Pgrab_error 3PROC , 105.Xr Prelease 3PROC 106