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 August 29, 2006
 27  .Os
 28  .Dt GELF_GETDYN 3
 29  .Sh NAME
 30  .Nm gelf_getdyn ,
 31  .Nm gelf_update_dyn
 32  .Nd read and update ELF dynamic entries
 33  .Sh LIBRARY
 34  .Lb libelf
 35  .Sh SYNOPSIS
 36  .In gelf.h
 37  .Ft "GElf_Dyn *"
 38  .Fn gelf_getdyn "Elf_Data *data" "int ndx" "GElf_Dyn *dyn"
 39  .Ft int
 40  .Fn gelf_update_dyn "Elf_Data *data" "int ndx" "GElf_Dyn *dyn"
 41  .Sh DESCRIPTION
 42  These convenience functions are used to retrieve and update class-dependent
 43  .Vt Elf32_Dyn
 44  or
 45  .Vt Elf64_Dyn
 46  information in the
 47  .Sy dynamic
 48  table of an ELF object.
 49  .Pp
 50  Argument
 51  .Ar data
 52  is an
 53  .Vt Elf_Data
 54  descriptor associated with a section of type
 55  .Dv SHT_DYNAMIC .
 56  Argument
 57  .Ar ndx
 58  is the index of the entry being retrieved or updated.
 59  The class-independent
 60  .Vt GElf_Dyn
 61  structure is described in
 62  .Xr gelf 3 .
 63  .Pp
 64  Function
 65  .Fn gelf_getdyn
 66  retrieves the class-dependent entry at index
 67  .Ar ndx
 68  in data buffer
 69  .Ar data
 70  and copies it to the destination pointed to by argument
 71  .Ar dyn
 72  after translation to class-independent form.
 73  .Pp
 74  Function
 75  .Fn gelf_update_dyn
 76  converts the class-independent entry pointed to
 77  by argument
 78  .Ar dyn
 79  to class-dependent form, and writes it to the entry at index
 80  .Ar ndx
 81  in the data buffer described by argument
 82  .Ar data .
 83  Function
 84  .Fn gelf_update_dyn
 85  signals an error if any of the values in the class-independent
 86  representation exceeds the representable limits of the target
 87  type.
 88  .Sh RETURN VALUES
 89  Function
 90  .Fn gelf_getdyn
 91  returns the value of argument
 92  .Ar dyn
 93  if successful, or NULL in case of an error.
 94  Function
 95  .Fn gelf_update_dyn
 96  returns a non-zero value if successful, or zero in case of an error.
 97  .Sh ERRORS
 98  These functions may fail with the following errors:
 99  .Bl -tag -width "[ELF_E_RESOURCE]"
100  .It Bq Er ELF_E_ARGUMENT
101  Arguments
102  .Ar data
103  or
104  .Ar dyn
105  were NULL.
106  .It Bq Er ELF_E_ARGUMENT
107  Argument
108  .Ar ndx
109  was less than zero or larger than the number of entries in the data
110  descriptor.
111  .It Bq Er ELF_E_ARGUMENT
112  Data descriptor
113  .Ar data
114  was not associated with a section of type
115  .Dv SHT_DYNAMIC .
116  .It Bq Er ELF_E_RANGE
117  A value was not representable in the target type.
118  .El
119  .Sh SEE ALSO
120  .Xr elf 3 ,
121  .Xr elf_getdata 3 ,
122  .Xr elf_getscn 3 ,
123  .Xr gelf 3