lib/libelf/elf_rand.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 17, 2006
  27 .Dt ELF_RAND 3
  28 .Os
  29 .Sh NAME
  30 .Nm elf_rand
  31 .Nd provide sequential access to the next archive member
  32 .Sh LIBRARY
  33 .Lb libelf
  34 .Sh SYNOPSIS
  35 .In libelf.h
  36 .Ft off_t
  37 .Fn elf_rand "Elf *archive" "off_t offset"
  38 .Sh DESCRIPTION
  39 The
  40 .Fn elf_rand
  41 function causes the ELF descriptor
  42 .Ar archive
  43 to be adjusted so that the next call to
  44 .Xr elf_begin 3
  45 will provide access to the archive member at byte offset
  46 .Ar offset
  47 in the archive.
  48 Argument
  49 .Ar offset
  50 is the byte offset from the start of the archive to the beginning of
  51 the archive header for the desired member.
  52 .Pp
  53 Archive member offsets may be retrieved using the
  54 .Xr elf_getarsym 3
  55 function.
  56 .Sh RETURN VALUES
  57 Function
  58 .Fn elf_rand
  59 returns
  60 .Ar offset
  61 if successful or zero in case of an error.
  62 .Sh EXAMPLES
  63 To process all the members of an archive use:
  64 .Bd -literal -offset indent
  65 off_t off;
  66 Elf *archive, *e;
  67 \&...
  68 cmd = ELF_C_READ;
  69 archive = elf_begin(fd, cmd, NULL);
  70 while ((e = elf_begin(fd, cmd, archive)) != (Elf *) 0)
  71 {
  72         ... process `e' here ...
  73         elf_end(e);
  74
  75         off = ...new value...;
  76         if (elf_rand(archive, off) != off) {
  77                 ... process error ...
  78         }
  79 }
  80 elf_end(archive);
  81 .Ed
  82 .Pp
  83 To rewind an archive, use:
  84 .Bd -literal -offset indent
  85 Elf *archive;
  86 \&...
  87 if (elf_rand(archive, SARMAG) != SARMAG) {
  88         ... error ...
  89 }
  90 .Ed
  91 .Sh ERRORS
  92 Function
  93 .Fn elf_rand
  94 may fail with the following errors:
  95 .Bl -tag -width "[ELF_E_RESOURCE]"
  96 .It Bq Er ELF_E_ARGUMENT
  97 Argument
  98 .Ar archive
  99 was null.
 100 .It Bq Er ELF_E_ARGUMENT
 101 Argument
 102 .Ar archive
 103 was not a descriptor for an
 104 .Xr ar 1
 105 archive.
 106 .It Bq Er ELF_E_ARCHIVE
 107 Argument
 108 .Ar offset
 109 did not correspond to the start of an archive member header.
 110 .El
 111 .Sh SEE ALSO
 112 .Xr ar 1 ,
 113 .Xr elf 3 ,
 114 .Xr elf_begin 3 ,
 115 .Xr elf_end 3 ,
 116 .Xr elf_getarsym 3 ,
 117 .Xr elf_next 3 ,
 118 .Xr gelf 3