lib/libelf/gelf_newphdr.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 August 25, 2006
  27 .Os
  28 .Dt GELF_NEWPHDR 3
  29 .Sh NAME
  30 .Nm elf32_newphdr ,
  31 .Nm elf64_newphdr ,
  32 .Nm gelf_newphdr
  33 .Nd allocate an ELF program header table
  34 .Sh LIBRARY
  35 .Lb libelf
  36 .Sh SYNOPSIS
  37 .In libelf.h
  38 .Ft "Elf32_Phdr *"
  39 .Fn elf32_newphdr "Elf *elf" "size_t count"
  40 .Ft "Elf64_Phdr *"
  41 .Fn elf64_newphdr "Elf *elf" "size_t count"
  42 .In gelf.h
  43 .Ft "void *"
  44 .Fn gelf_newphdr "Elf *elf" "size_t count"
  45 .Sh DESCRIPTION
  46 These functions allocate an ELF Program Header table
  47 for an ELF descriptor.
  48 .Vt Elf32_Phdr
  49 and
  50 .Vt Elf64_Phdr
  51 descriptors are described further in
  52 .Xr elf 5 .
  53 .Pp
  54 Functions
  55 .Fn elf32_newphdr
  56 and
  57 .Fn elf64_newphdr
  58 allocate a table of
  59 .Ar count
  60 .Vt Elf32_Phdr
  61 and
  62 .Vt Elf64_Phdr
  63 descriptors respectively,
  64 discarding any existing program header table
  65 already present in the ELF descriptor
  66 .Ar elf .
  67 A value of zero for argument
  68 .Ar count
  69 may be used to delete an existing program header table
  70 from an ELF descriptor.
  71 .Pp
  72 Function
  73 .Fn gelf_newphdr
  74 will return a table of
  75 .Vt Elf32_Phdr
  76 or
  77 .Vt Elf64_Phdr
  78 with
  79 .Ar count
  80 elements depending on the ELF class of ELF descriptor
  81 .Ar elf .
  82 .Pp
  83 The functions set the
  84 .Va e_phnum
  85 field of the executable header for ELF descriptor
  86 .Ar elf
  87 to
  88 .Ar count ,
  89 and also set the
  90 .Dv ELF_F_DIRTY
  91 bit on the program header table.
  92 All members of the returned array of Phdr structures
  93 will be initialized to zero.
  94 .Pp
  95 After a successful call to these functions, the pointer returned
  96 by a prior call to
  97 .Fn elf32_getphdr
  98 or
  99 .Fn elf64_getphdr
 100 on the same descriptor
 101 .Ar elf
 102 will no longer be valid.
 103 .Sh RETURN VALUES
 104 The functions a valid pointer if successful, or NULL in case an error
 105 was encountered.
 106 .Sh ERRORS
 107 These functions may fail with the following errors:
 108 .Bl -tag -width "[ELF_E_RESOURCE]"
 109 .It Bq Er ELF_E_ARGUMENT
 110 Argument
 111 .Ar elf
 112 was NULL.
 113 .It Bq Er ELF_E_ARGUMENT
 114 Argument
 115 .Ar elf
 116 was not a descriptor for an ELF object.
 117 .It Bq Er ELF_E_CLASS
 118 ELF descriptor
 119 .Ar elf
 120 was of an unrecognized class.
 121 .It Bq Er ELF_E_RESOURCE
 122 An out of memory condition was detected.
 123 .It Bq Er ELF_E_SEQUENCE
 124 An executable header was not allocated for ELF descriptor
 125 .Ar elf
 126 before using these APIs.
 127 .El
 128 .Sh SEE ALSO
 129 .Xr elf 3 ,
 130 .Xr elf32_getphdr 3 ,
 131 .Xr elf32_newehdr 3 ,
 132 .Xr elf64_getphdr 3 ,
 133 .Xr elf64_newehdr 3 ,
 134 .Xr elf_flagphdr 3 ,
 135 .Xr gelf 3 ,
 136 .Xr gelf_getphdr 3 ,
 137 .Xr gelf_newehdr 3 ,
 138 .Xr elf 5