contrib/elftoolchain/libelf/elf_begin.3

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