1.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" This software is provided by Joseph Koshy ``as is'' and 13.\" any express or implied warranties, including, but not limited to, the 14.\" implied warranties of merchantability and fitness for a particular purpose 15.\" are disclaimed. in no event shall Joseph Koshy be liable 16.\" for any direct, indirect, incidental, special, exemplary, or consequential 17.\" damages (including, but not limited to, procurement of substitute goods 18.\" or services; loss of use, data, or profits; or business interruption) 19.\" however caused and on any theory of liability, whether in contract, strict 20.\" liability, or tort (including negligence or otherwise) arising in any way 21.\" out of the use of this software, even if advised of the possibility of 22.\" such damage. 23.\" 24.\" $Id: elf_memory.3 3639 2018-10-14 14:07:02Z jkoshy $ 25.\" 26.Dd June 28, 2006 27.Dt ELF_MEMORY 3 28.Os 29.Sh NAME 30.Nm elf_memory 31.Nd process an ELF or ar(1) archive mapped into memory 32.Sh LIBRARY 33.Lb libelf 34.Sh SYNOPSIS 35.In libelf.h 36.Ft "Elf *" 37.Fn elf_memory "char *image" "size_t size" 38.Sh DESCRIPTION 39Function 40.Fn elf_memory 41is used to process an ELF file or 42.Xr ar 1 43archive whose image is present in memory. 44.Pp 45Argument 46.Ar image 47points to the start of the memory image of the file or archive. 48Argument 49.Ar size 50contains the size in bytes of the memory image. 51.Pp 52The ELF descriptor is created for reading (i.e., analogous to the 53use of 54.Xr elf_begin 3 55with a command argument value of 56.Dv ELF_C_READ Ns ). 57.Sh RETURN VALUES 58Function 59.Fn elf_memory 60returns a pointer to a new ELF descriptor if successful, or NULL if an 61error occurred. 62.Pp 63The return value may be queried for the file type using 64.Xr elf_kind 3 . 65.Sh EXAMPLES 66To read parse an elf file, use: 67.Bd -literal -offset indent 68int fd; 69void *p; 70struct stat sb; 71Elf *e; 72\&... 73if ((fd = open("./elf-file", O_RDONLY)) < 0 || 74 fstat(fd, &sb) < 0 || 75 (p = mmap(NULL, sb.st_size, PROT_READ, MAP_PRIVATE, fd, (off_t) 0)) == 76 MAP_FAILED) { 77 ... handle system error ... 78} 79 80if ((e = elf_memory(p, sb.st_size)) == NULL) { 81 ... handle elf(3) error ... 82} 83\&... use ELF descriptor "e" here ... 84.Ed 85.Sh ERRORS 86Function 87.Fn elf_memory 88can fail with the following errors: 89.Bl -tag -width "[ELF_E_RESOURCE]" 90.It Bq Er ELF_E_ARGUMENT 91A NULL value was used for argument 92.Ar image 93or the value of argument 94.Ar sz 95was zero. 96.It Bq Er ELF_E_HEADER 97The header of the ELF object contained an unsupported value in its 98.Va e_ident[EI_CLASS] 99field. 100.It Bq Er ELF_E_HEADER 101The header of the ELF object contained an unsupported value in its 102.Va e_ident[EI_DATA] 103field. 104.It Bq Er ELF_E_RESOURCE 105An out of memory condition was detected. 106.It Bq Er ELF_E_SEQUENCE 107Function 108.Fn elf_memory 109was called before a working version was set using 110.Xr elf_version 3 . 111.It Bq Er ELF_E_VERSION 112The ELF object referenced by argument 113.Ar image 114was of an unsupported ELF version. 115.El 116.Sh SEE ALSO 117.Xr elf 3 , 118.Xr elf_begin 3 , 119.Xr elf_end 3 , 120.Xr elf_errno 3 , 121.Xr elf_kind 3 , 122.Xr gelf 3 123