lib/libelf/elf_begin.3

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