1.\" $NetBSD: elf_begin.3,v 1.6 2024/03/03 17:37:33 christos Exp $ 2.\" 3.\" Copyright (c) 2006,2008-2011 Joseph Koshy. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" This software is provided by Joseph Koshy ``as is'' and 15.\" any express or implied warranties, including, but not limited to, the 16.\" implied warranties of merchantability and fitness for a particular purpose 17.\" are disclaimed. in no event shall Joseph Koshy be liable 18.\" for any direct, indirect, incidental, special, exemplary, or consequential 19.\" damages (including, but not limited to, procurement of substitute goods 20.\" or services; loss of use, data, or profits; or business interruption) 21.\" however caused and on any theory of liability, whether in contract, strict 22.\" liability, or tort (including negligence or otherwise) arising in any way 23.\" out of the use of this software, even if advised of the possibility of 24.\" such damage. 25.\" 26.\" Id: elf_begin.3 3952 2022-03-12 09:09:50Z jkoshy 27.\" 28.Dd December 11, 2011 29.Dt ELF_BEGIN 3 30.Os 31.Sh NAME 32.Nm elf_begin 33.Nd open an ELF file or ar(1) archive 34.Sh LIBRARY 35.Lb libelf 36.Sh SYNOPSIS 37.In libelf.h 38.Ft "Elf *" 39.Fn elf_begin "int fd" "Elf_Cmd cmd" "Elf *elf" 40.Sh DESCRIPTION 41Function 42.Fn elf_begin 43is used to open ELF files and 44.Xr ar 1 45archives for further processing by other APIs in the 46.Xr elf 3 47library. 48It is also used to access individual ELF members of an 49.Xr ar 1 50archive in combination with the 51.Xr elf_next 3 52and 53.Xr elf_rand 3 54APIs. 55.Pp 56Argument 57.Fa fd 58is an open file descriptor returned from an 59.Xr open 2 60system call. 61Function 62.Fn elf_begin 63uses argument 64.Fa fd 65for reading or writing depending on the value of argument 66.Fa cmd . 67Argument 68.Fa elf 69is primarily used for iterating through archives. 70.Pp 71The argument 72.Fa cmd 73can have the following values: 74.Bl -tag -width "ELF_C_WRITE" 75.It ELF_C_NULL 76Causes 77.Fn elf_begin 78to return 79.Dv NULL . 80Arguments 81.Fa fd 82and 83.Fa elf 84are ignored, and no additional error is signalled. 85.It ELF_C_READ 86This value is to be when the application wishes to examine (but not 87modify) the contents of the file specified by the arguments 88.Fa fd 89and 90.Fa elf . 91It can be used for both 92.Xr ar 1 93archives and for ELF objects. 94.Pp 95If argument 96.Fa elf 97is 98.Dv NULL , 99the library will allocate a new ELF descriptor for the file 100being processed. 101The argument 102.Fa fd 103should have been opened for reading. 104.Pp 105If argument 106.Fa elf 107is not 108.Dv NULL , 109and references a regular ELF file previously opened with 110.Fn elf_begin , 111then the activation count for the descriptor referenced by argument 112.Fa elf 113is incremented. 114The value in argument 115.Fa fd 116should match that used to open the descriptor argument 117.Fa elf . 118.Pp 119If argument 120.Fa elf 121is not 122.Dv NULL , 123and references a descriptor for an 124.Xr ar 1 125archive opened earlier with 126.Fn elf_begin , 127a descriptor for an element in the archive is returned as 128described in the section 129.Sx "Processing ar(1) archives" 130below. 131The value for argument 132.Fa fd 133should match that used to open the archive earlier. 134.Pp 135If argument 136.Fa elf 137is not 138.Dv NULL , 139and references an 140.Xr ar 1 141archive opened earlier with 142.Fn elf_memory , 143then the value of the argument 144.Fa fd 145is ignored. 146.It Dv ELF_C_RDWR 147This command is used to prepare an ELF file for reading and writing. 148This command is not supported for 149.Xr ar 1 150archives. 151.Pp 152Argument 153.Fa fd 154should have been opened for reading and writing. 155If argument 156.Fa elf 157is 158.Dv NULL , 159the library will allocate a new ELF descriptor for 160the file being processed. 161If the argument 162.Fa elf 163is non-null, it should point to a descriptor previously 164allocated with 165.Fn elf_begin 166with the same values for arguments 167.Fa fd 168and 169.Fa cmd ; 170in this case the library will increment the activation count for descriptor 171.Fa elf 172and return the same descriptor. 173.Pp 174Changes to the in-memory image of the ELF file may be written back to 175disk using the 176.Xr elf_update 3 177function. 178.It Dv ELF_C_WRITE 179This command is used when the application wishes to create a new ELF 180file. 181Argument 182.Fa fd 183should have been opened for writing. 184Argument 185.Fa elf 186is ignored, and the previous contents of file referenced by argument 187.Fa fd 188are overwritten. 189.El 190.Ss Processing ar(1) archives 191An 192.Xr ar 1 193archive may be opened in read mode (with argument 194.Fa cmd 195set to 196.Dv ELF_C_READ ) 197using 198.Fn elf_begin 199or 200.Fn elf_memory . 201The returned ELF descriptor can be passed into to 202subsequent calls to 203.Fn elf_begin 204to access individual members of the archive. 205.Pp 206Random access within an opened archive is possible using 207the 208.Xr elf_next 3 209and 210.Xr elf_rand 3 211functions. 212.Pp 213The symbol table of the archive may be retrieved 214using 215.Xr elf_getarsym 3 . 216.Sh RETURN VALUES 217The function returns a pointer to a ELF descriptor if successful, or 218.Dv NULL 219if an error occurred. 220.Sh EXAMPLES 221To iterate through the members of an 222.Xr ar 1 223archive, use: 224.Bd -literal -offset indent 225Elf_Cmd c; 226Elf *ar_e, *elf_e; 227\&... 228c = ELF_C_READ; 229if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) { 230 \&... handle error in opening the archive ... 231} 232while ((elf_e = elf_begin(fd, c, ar_e)) != 0) { 233 \&... process member referenced by elf_e here ... 234 c = elf_next(elf_e); 235 elf_end(elf_e); 236} 237.Ed 238.Pp 239To create a new ELF file, use: 240.Bd -literal -offset indent 241int fd; 242Elf *e; 243\&... 244if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) < 0) { 245 \&... handle the error from open(2) ... 246} 247if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) { 248 \&... handle the error from elf_begin() ... 249} 250\&... create the ELF image using other elf(3) APIs ... 251elf_update(e, ELF_C_WRITE); 252elf_end(e); 253.Ed 254.Sh ERRORS 255Function 256.Fn elf_begin 257can fail with the following errors: 258.Bl -tag -width "[ELF_E_RESOURCE]" 259.It Bq Er ELF_E_ARCHIVE 260The archive denoted by argument 261.Fa elf 262could not be parsed. 263.It Bq Er ELF_E_ARGUMENT 264The value in argument 265.Fa cmd 266was unrecognized. 267.It Bq Er ELF_E_ARGUMENT 268A non-null value for argument 269.Fa elf 270was specified when 271.Fa cmd 272was set to 273.Dv ELF_C_RDWR . 274.It Bq Er ELF_E_ARGUMENT 275The value of argument 276.Fa fd 277differs from the one the ELF descriptor 278.Fa elf 279was created with. 280.It Bq Er ELF_E_ARGUMENT 281Argument 282.Fa cmd 283differs from the value specified when ELF descriptor 284.Fa elf 285was created. 286.It Bq Er ELF_E_ARGUMENT 287An 288.Xr ar 1 289archive was opened with 290.Fa cmd 291set to 292.Dv ELF_C_RDWR . 293.It Bq Er ELF_E_ARGUMENT 294The file referenced by argument 295.Fa fd 296was empty. 297.It Bq Er ELF_E_ARGUMENT 298The underlying file for argument 299.Fa fd 300was of an unsupported type. 301.It Bq Er ELF_E_IO 302The file descriptor in argument 303.Fa fd 304was invalid. 305.It Bq Er ELF_E_IO 306The file descriptor in argument 307.Fa fd 308could not be read or written to. 309.It Bq Er ELF_E_RESOURCE 310An out of memory condition was encountered. 311.It Bq Er ELF_E_SEQUENCE 312Function 313.Fn elf_begin 314was called before a working version was established with 315.Xr elf_version 3 . 316.It Bq Er ELF_E_VERSION 317The ELF object referenced by argument 318.Fa fd 319was of an unsupported ELF version. 320.El 321.Sh SEE ALSO 322.Xr elf 3 , 323.Xr elf_end 3 , 324.Xr elf_errno 3 , 325.Xr elf_memory 3 , 326.Xr elf_next 3 , 327.Xr elf_rand 3 , 328.Xr elf_update 3 , 329.Xr gelf 3 330