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 21, 2006
  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
  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 The returned ELF descriptor can be passed into to
 168 subsequent calls to
 169 .Fn elf_begin
 170 to access individual members of the archive.
 171 .Pp
 172 Random access within an opened archive is possible using
 173 the
 174 .Xr elf_next 3
 175 and
 176 .Xr elf_rand 3
 177 functions.
 178 .Pp
 179 The symbol table of the archive may be retrieved
 180 using
 181 .Xr elf_getarsym 3 .
 182 .Sh RETURN VALUES
 183 The function returns a pointer to a ELF descriptor if successful, or NULL
 184 if an error occurred.
 185 .Sh EXAMPLES
 186 To iterate through the members of an
 187 .Xr ar 1
 188 archive, use:
 189 .Bd -literal -offset indent
 190 Elf_Cmd c;
 191 Elf *ar_e, *elf_e;
 192 \&...
 193 c = ELF_C_READ;
 194 if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) {
 195         \&... handle error in opening the archive ...
 196 }
 197 while ((elf_e = elf_begin(fd, c, ar_e)) != 0) {
 198         \&... process member referenced by elf_e here ...
 199         c = elf_next(elf_e);
 200         elf_end(elf_e);
 201 }
 202 .Ed
 203 .Pp
 204 To create a new ELF file, use:
 205 .Bd -literal -offset indent
 206 int fd;
 207 Elf *e;
 208 \&...
 209 if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) < 0) {
 210         \&... handle the error from open(2) ...
 211 }
 212 if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) {
 213         \&... handle the error from elf_begin() ...
 214 }
 215 \&... create the ELF image using other elf(3) APIs ...
 216 elf_update(e, ELF_C_WRITE);
 217 elf_end(e);
 218 .Ed
 219 .Sh ERRORS
 220 Function
 221 .Fn elf_begin
 222 can fail with the following errors:
 223 .Pp
 224 .Bl -tag -width "[ELF_E_RESOURCE]"
 225 .It Bq Er ELF_E_ARGUMENT
 226 An unrecognized value was specified in argument
 227 .Ar cmd .
 228 .It Bq Er ELF_E_ARGUMENT
 229 A non-null value for argument
 230 .Ar elf
 231 was specified when
 232 .Ar cmd
 233 was set to
 234 .Dv ELF_C_RDWR .
 235 .It Bq Er ELF_E_ARGUMENT
 236 The value of argument
 237 .Ar fd
 238 differs from the one the ELF descriptor
 239 .Ar elf
 240 was created with.
 241 .It Bq Er ELF_E_ARGUMENT
 242 Argument
 243 .Ar cmd
 244 differs from the value specified when ELF descriptor
 245 .Ar elf
 246 was created.
 247 .It Bq Er ELF_E_ARGUMENT
 248 Argument
 249 .Ar elf
 250 was not a descriptor for an
 251 .Xr ar 1
 252 archive.
 253 .It Bq Er ELF_E_ARGUMENT
 254 An
 255 .Xr ar 1
 256 archive was opened with with
 257 .Ar cmd
 258 set to
 259 .Dv ELF_C_RDWR .
 260 .It Bq Er ELF_E_IO
 261 Function
 262 .Fn elf_begin
 263 was unable to truncate a file opened for writing using
 264 .Dv ELF_C_WRITE .
 265 .It Bq Er ELF_E_RESOURCE
 266 An out of memory condition was encountered.
 267 .It Bq Er ELF_E_SEQUENCE
 268 Function
 269 .Fn elf_begin
 270 was called before a working version was established with
 271 .Xr elf_version 3 .
 272 .El
 273 .Sh SEE ALSO
 274 .Xr elf 3 ,
 275 .Xr elf_end 3 ,
 276 .Xr elf_errno 3 ,
 277 .Xr elf_memory 3 ,
 278 .Xr elf_next 3 ,
 279 .Xr elf_rand 3 ,
 280 .Xr elf_update 3 ,
 281 .Xr gelf 3