| .\" |
| .\" This file and its contents are supplied under the terms of the |
| .\" Common Development and Distribution License ("CDDL"), version 1.0. |
| .\" You may only use this file in accordance with the terms of version |
| .\" 1.0 of the CDDL. |
| .\" |
| .\" A full copy of the text of the CDDL should have accompanied this |
| .\" source. A copy of the CDDL is also available via the Internet at |
| .\" http://www.illumos.org/license/CDDL. |
| .\" |
| .\" |
| .\" Copyright 2015 Joyent, Inc. |
| .\" |
| .Dd May 11, 2016 |
| .Dt PGRAB_FILE 3PROC |
| .Os |
| .Sh NAME |
| .Nm Pgrab_file |
| .Nd grab and inspect an ELF object |
| .Sh SYNOPSIS |
| .Lb libproc |
| .In libproc.h |
| .Ft struct ps_prochandle |
| .Fo Pgrab_file |
| .Fa "const char *fname" |
| .Fa "int *perr" |
| .Fc |
| .Sh DESCRIPTION |
| The |
| .Fn Pgrab_file |
| function creates a handle to the ELF object contained in file |
| .Fa fname . |
| This handle is considered an |
| .Em idle |
| handle, it allows one to inspect aspects of the ELF contents present in |
| the handle, for example obtaining CTF information and looking up |
| symbols. |
| .Pp |
| There is no running state associated with this handle nor can there be. |
| If one intends to control a running process or create a process, see |
| .Xr Pgrab 3PROC |
| and |
| .Xr Pcreate 3PROC |
| respectively. |
| To inspect a core file use |
| .Xr Pgrab_core 3PROC . |
| .Pp |
| The |
| .Fa perr |
| argument must be a |
| .Pf non- Dv NULL |
| pointer which will store a more detailed error in the event that |
| .Fn Pgrab_file |
| fails. |
| A human-readable form of the error can be obtained with |
| .Xr Pgrab_error 3PROC . |
| .Pp |
| When finished with the returned handle, |
| .Xr Prelease 3PROC |
| must be called to clean up resources associated with it. |
| .Sh RETURN VALUES |
| Upon successful completion, the |
| .Fn Pgrab_file |
| function returns a control handle to the process. |
| Otherwise, |
| .Dv NULL |
| is returned and |
| .Fa perr |
| is filled in with an error code. |
| .Sh ERRORS |
| .Bl -tag -width Er -offset indent |
| .It Er G_ELF |
| An unexpected |
| .Xr libelf 3LIB |
| failure occurred while processing the file named by |
| .Fa fname . |
| .It Er G_FORMAT |
| The file named by |
| .Fa fname |
| is not a valid ELF file. |
| .It Er G_NOEXEC |
| The file named by |
| .Fa fname |
| does not exist. |
| .It Er G_STRANGE |
| An unanticipated system error occurred while trying to grab the |
| file |
| .Fa fname |
| and create the handle. |
| The value of |
| .Sy errno |
| indicates the system failure. |
| .El |
| .Sh INTERFACE STABILITY |
| .Sy Uncommitted |
| .Sh MT-LEVEL |
| .Sy MT-Safe |
| .Sh SEE ALSO |
| .Xr errno 3C , |
| .Xr libelf 3LIB , |
| .Xr libproc 3LIB , |
| .Xr Pfree 3PROC , |
| .Xr Pgrab_core 3PROC , |
| .Xr Pgrab_error 3PROC , |
| .Xr Prelease 3PROC |