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