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$ 
 25  .\"
 26  .Dd December 11, 2011
 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 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 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