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