1.\" Copyright (c) 2006 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.\" $FreeBSD$ 25.\" 26.Dd June 20, 2010 27.Dt ELF_BEGIN 3 28.Os 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 argument 85.Ar fd . 86It can be used for both 87.Xr ar 1 88archives and for regular ELF files. 89.Pp 90Argument 91.Ar fd 92should have been opened for reading. 93If argument 94.Ar elf 95is NULL, the library will allocate a new ELF descriptor for 96the file being processed. 97If argument 98.Ar elf 99is not NULL, and references a regular ELF file previously opened with 100.Fn elf_begin , 101then the activation count for 102.Ar elf 103is incremented. 104If argument 105.Ar elf 106is not NULL, and references a descriptor for an 107.Xr ar 1 108archive opened earlier with 109.Fn elf_begin , 110a descriptor for an element in the archive is returned as 111described in the section 112.Sx "Processing ar(1) archives" 113below. 114.It Dv ELF_C_RDWR 115The command is used to prepare an ELF file for reading and writing. 116It is not supported for archives. 117.Pp 118Argument 119.Ar fd 120should have been opened for reading and writing. 121If argument 122.Ar elf 123is NULL, the library will allocate a new ELF descriptor for 124the file being processed. 125If the argument 126.Ar elf 127is non-null, it should point to a descriptor previously 128allocated with 129.Fn elf_begin 130with the same values for arguments 131.Ar fd 132and 133.Ar cmd ; 134in this case the library will increment the activation count for descriptor 135.Ar elf 136and return the same descriptor. 137Changes to the in-memory image of the ELF file are written back to 138disk using the 139.Xr elf_update 3 140function. 141.Pp 142This command is not valid for 143.Xr ar 1 144archives. 145.It Dv ELF_C_WRITE 146This command is used when the application wishes to create a new ELF 147file. 148Argument 149.Ar fd 150should have been opened for writing. 151Argument 152.Ar elf 153is ignored, and the previous contents of file referenced by 154argument 155.Ar fd 156are overwritten. 157.El 158.Ss Processing ar(1) archives 159An 160.Xr ar 1 161archive may be opened in read mode (with argument 162.Ar cmd 163set to 164.Dv ELF_C_READ ) 165using 166.Fn elf_begin 167or 168.Fn elf_memory . 169The returned ELF descriptor can be passed into to 170subsequent calls to 171.Fn elf_begin 172to access individual members of the archive. 173.Pp 174Random access within an opened archive is possible using 175the 176.Xr elf_next 3 177and 178.Xr elf_rand 3 179functions. 180.Pp 181The symbol table of the archive may be retrieved 182using 183.Xr elf_getarsym 3 . 184.Sh RETURN VALUES 185The function returns a pointer to a ELF descriptor if successful, or NULL 186if an error occurred. 187.Sh EXAMPLES 188To iterate through the members of an 189.Xr ar 1 190archive, use: 191.Bd -literal -offset indent 192Elf_Cmd c; 193Elf *ar_e, *elf_e; 194\&... 195c = ELF_C_READ; 196if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) { 197 \&... handle error in opening the archive ... 198} 199while ((elf_e = elf_begin(fd, c, ar_e)) != 0) { 200 \&... process member referenced by elf_e here ... 201 c = elf_next(elf_e); 202 elf_end(elf_e); 203} 204.Ed 205.Pp 206To create a new ELF file, use: 207.Bd -literal -offset indent 208int fd; 209Elf *e; 210\&... 211if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) < 0) { 212 \&... handle the error from open(2) ... 213} 214if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) { 215 \&... handle the error from elf_begin() ... 216} 217\&... create the ELF image using other elf(3) APIs ... 218elf_update(e, ELF_C_WRITE); 219elf_end(e); 220.Ed 221.Sh ERRORS 222Function 223.Fn elf_begin 224can fail with the following errors: 225.Bl -tag -width "[ELF_E_RESOURCE]" 226.It Bq Er ELF_E_ARCHIVE 227The archive denoted by argument 228.Ar elf 229could not be parsed. 230.It Bq Er ELF_E_ARGUMENT 231An unrecognized value was specified in argument 232.Ar cmd . 233.It Bq Er ELF_E_ARGUMENT 234A non-null value for argument 235.Ar elf 236was specified when 237.Ar cmd 238was set to 239.Dv ELF_C_RDWR . 240.It Bq Er ELF_E_ARGUMENT 241The value of argument 242.Ar fd 243differs from the one the ELF descriptor 244.Ar elf 245was created with. 246.It Bq Er ELF_E_ARGUMENT 247Argument 248.Ar cmd 249differs from the value specified when ELF descriptor 250.Ar elf 251was created. 252.It Bq Er ELF_E_ARGUMENT 253An 254.Xr ar 1 255archive was opened with 256.Ar cmd 257set to 258.Dv ELF_C_RDWR . 259.It Bq Er ELF_E_IO 260Function 261.Fn elf_begin 262was unable to truncate a file opened for writing using 263.Dv ELF_C_WRITE . 264.It Bq Er ELF_E_RESOURCE 265An out of memory condition was encountered. 266.It Bq Er ELF_E_SEQUENCE 267Function 268.Fn elf_begin 269was called before a working version was established with 270.Xr elf_version 3 . 271.El 272.Sh SEE ALSO 273.Xr elf 3 , 274.Xr elf_end 3 , 275.Xr elf_errno 3 , 276.Xr elf_memory 3 , 277.Xr elf_next 3 , 278.Xr elf_rand 3 , 279.Xr elf_update 3 , 280.Xr gelf 3 281