lib/libelf/gelf_newphdr.3

   1 .\" Copyright (c) 2006,2007 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 October 22, 2007
  27 .Dt GELF_NEWPHDR 3
  28 .Os
  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 .Dv ELF_F_DIRTY
  85 flag on the program header table.
  86 All members of the returned array of Phdr structures
  87 will be initialized to zero.
  88 .Pp
  89 After a successful call to these functions, the pointer returned
  90 by a prior call to
  91 .Fn elf32_getphdr
  92 or
  93 .Fn elf64_getphdr
  94 on the same descriptor
  95 .Ar elf
  96 will no longer be valid.
  97 .Sh RETURN VALUES
  98 The functions a valid pointer if successful, or NULL in case an error
  99 was encountered.
 100 .Sh ERRORS
 101 These functions may fail with the following errors:
 102 .Bl -tag -width "[ELF_E_RESOURCE]"
 103 .It Bq Er ELF_E_ARGUMENT
 104 Argument
 105 .Ar elf
 106 was NULL.
 107 .It Bq Er ELF_E_ARGUMENT
 108 Argument
 109 .Ar elf
 110 was not a descriptor for an ELF object.
 111 .It Bq Er ELF_E_CLASS
 112 ELF descriptor
 113 .Ar elf
 114 was of an unrecognized class.
 115 .It Bq Er ELF_E_RESOURCE
 116 An out of memory condition was detected.
 117 .It Bq Er ELF_E_SEQUENCE
 118 An executable header was not allocated for ELF descriptor
 119 .Ar elf
 120 before using these APIs.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr elf 3 ,
 124 .Xr elf32_getphdr 3 ,
 125 .Xr elf32_newehdr 3 ,
 126 .Xr elf64_getphdr 3 ,
 127 .Xr elf64_newehdr 3 ,
 128 .Xr elf_flagphdr 3 ,
 129 .Xr elf_getphnum 3 ,
 130 .Xr gelf 3 ,
 131 .Xr gelf_getphdr 3 ,
 132 .Xr gelf_newehdr 3 ,
 133 .Xr elf 5