1  .\" Copyright (c) 2006,2008 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 June 17, 2006
 27  .Os
 28  .Dt ELF_RAND 3
 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