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 October 22, 2007
 27  .Os
 28  .Dt GELF_NEWEHDR 3
 29  .Sh NAME
 30  .Nm elf32_newehdr ,
 31  .Nm elf64_newehdr ,
 32  .Nm gelf_newehdr
 33  .Nd retrieve or allocate the object file header
 34  .Sh LIBRARY
 35  .Lb libelf
 36  .Sh SYNOPSIS
 37  .In libelf.h
 38  .Ft "Elf32_Ehdr *"
 39  .Fn elf32_newehdr "Elf *elf"
 40  .Ft "Elf64_Ehdr *"
 41  .Fn elf64_newehdr "Elf *elf"
 42  .In gelf.h
 43  .Ft "void *"
 44  .Fn gelf_newehdr "Elf *elf" "int elfclass"
 45  .Sh DESCRIPTION
 46  These functions retrieve the ELF header from the ELF descriptor
 47  .Ar elf ,
 48  allocating a new header if needed.
 49  File data structures are translated to their in-memory representations
 50  as described in
 51  .Xr elf 3 .
 52  .Pp
 53  Function
 54  .Fn elf32_newehdr
 55  returns a pointer to a 32 bit
 56  .Vt Elf32_Ehdr
 57  structure.
 58  Function
 59  .Fn elf64_newehdr
 60  returns a pointer to a 64 bit
 61  .Vt Elf64_Ehdr structure.
 62  .Pp
 63  When argument
 64  .Ar elfclass
 65  has value
 66  .Dv ELFCLASS32 ,
 67  function
 68  .Fn gelf_newehdr
 69  returns the value returned by
 70  .Fn elf32_newehdr "elf" .
 71  When argument
 72  .Ar elfclass
 73  has value
 74  .Dv ELFCLASS64
 75  it returns the value returned by
 76  .Fn elf64_newehdr "elf" .
 77  .Pp
 78  If a fresh header structure is allocated, the members of the
 79  structure are initialized as follows:
 80  .Bl -tag -width indent
 81  .It Va "e_ident[EI_MAG0..EI_MAG3]"
 82  Identification bytes at offsets
 83  .Dv EI_MAG0 ,
 84  .Dv EI_MAG1 ,
 85  .Dv EI_MAG2
 86  and
 87  .Dv EI_MAG3
 88  are set to the ELF signature.
 89  .It Va "e_ident[EI_CLASS]"
 90  The identification byte at offset
 91  .Dv EI_CLASS
 92  is set to the ELF class associated with the function being called
 93  or to argument
 94  .Ar elfclass
 95  for function
 96  .Fn gelf_newehdr .
 97  .It Va "e_ident[EI_DATA]"
 98  The identification byte at offset
 99  .Dv EI_DATA
100  is set to
101  .Dv ELFDATANONE .
102  .It Va "e_ident[EI_VERSION]"
103  The identification byte at offset
104  .Dv EI_VERSION
105  is set to the ELF library's operating version set by a prior call to
106  .Xr elf_version 3 .
107  .It Va e_machine
108  is set to
109  .Dv EM_NONE .
110  .It Va e_type
111  is set to
112  .Dv ELF_K_NONE .
113  .It Va e_version
114  is set to the ELF library's operating version set by a prior call to
115  .Xr elf_version 3 .
116  .El
117  .Pp
118  Other members of the header are set to zero.
119  The application is responsible for changing these values
120  as needed before calling
121  .Fn elf_update .
122  .Pp
123  If successful, these three functions set the
124  .Dv ELF_F_DIRTY
125  flag on ELF descriptor
126  .Ar elf .
127  .Sh RETURN VALUES
128  These functions return a pointer to a translated header descriptor
129  if successful, or NULL on failure.
130  .Sh ERRORS
131  These functions can fail with the following errors:
132  .Bl -tag -width "[ELF_E_RESOURCE]"
133  .It Bq Er ELF_E_ARGUMENT
134  The argument
135  .Ar elf
136  was null.
137  .It Bq Er ELF_E_ARGUMENT
138  Argument
139  .Ar elf
140  was not a descriptor for an ELF object.
141  .It Bq Er ELF_E_ARGUMENT
142  Argument
143  .Ar elfclass
144  had an unsupported value.
145  .It Bq Er ELF_E_ARGUMENT
146  The class of the ELF descriptor
147  .Ar elf
148  did not match that of the requested operation.
149  .It Bq Er ELF_E_ARGUMENT
150  For function
151  .Fn gelf_newehdr ,
152  the class of argument
153  .Ar elf
154  was not
155  .Dv ELFCLASSNONE
156  and did not match the argument
157  .Ar elfclass .
158  .It Bq Er ELF_E_CLASS
159  The ELF class of descriptor
160  .Ar elf
161  did not match that of the API function being called.
162  .It Bq Er ELF_E_HEADER
163  A malformed ELF header was detected.
164  .It Bq Er ELF_E_RESOURCE
165  An out of memory condition was detected during execution.
166  .It Bq Er ELF_E_SECTION
167  The ELF descriptor in argument
168  .Ar elf
169  did not adhere to the conventions used for extended numbering.
170  .It Bq Er ELF_E_VERSION
171  The ELF descriptor
172  .Ar elf
173  had an unsupported ELF version number.
174  .El
175  .Sh SEE ALSO
176  .Xr elf 3 ,
177  .Xr elf32_getehdr 3 ,
178  .Xr elf64_getehdr 3 ,
179  .Xr elf_flagdata 3 ,
180  .Xr elf_getident 3 ,
181  .Xr elf_update 3 ,
182  .Xr elf_version 3 ,
183  .Xr gelf 3 ,
184  .Xr gelf_getehdr 3 ,
185  .Xr elf 5