contrib/elftoolchain/libelftc/elftc_bfd_find_target.3

   1 .\" Copyright (c) 2010-2011 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: elftc_bfd_find_target.3 3752 2019-06-28 01:12:53Z emaste $
  25 .\"
  26 .Dd February 12, 2020
  27 .Dt ELFTC_BFD_FIND_TARGET 3
  28 .Os
  29 .Sh NAME
  30 .Nm elftc_bfd_find_target ,
  31 .Nm elftc_bfd_target_byteorder ,
  32 .Nm elftc_bfd_target_class ,
  33 .Nm elftc_bfd_target_flavor ,
  34 .Nm elftc_bfd_target_machine
  35 .Nd binary object descriptor handling
  36 .Sh LIBRARY
  37 .Lb libelftc
  38 .Sh SYNOPSIS
  39 .In libelftc.h
  40 .Vt struct Elftc_Bfd_Target;
  41 .Ft "Elftc_Bfd_Target *"
  42 .Fn elftc_bfd_find_target "const char *target_name"
  43 .Ft "unsigned int"
  44 .Fn elftc_bfd_target_class "Elftc_Bfd_Target *target"
  45 .Ft "unsigned int"
  46 .Fn elftc_bfd_target_byteorder "Elftc_Bfd_Target *target"
  47 .Ft Elftc_Bfd_Target_Flavor
  48 .Fn elftc_bfd_target_flavor "Elftc_Bfd_Target *target"
  49 .Ft "unsigned int"
  50 .Fn elftc_bfd_target_machine "Elftc_Bfd_Target *target"
  51 .Ft "unsigned int"
  52 .Fn elftc_bfd_target_osabi "Elftc_Bfd_Target *target"
  53 .Sh DESCRIPTION
  54 Function
  55 .Fn elftc_bfd_find_target
  56 locates a binary object descriptor corresponding to the descriptor
  57 name in argument
  58 .Ar "target_name" .
  59 Binary object descriptors encapsulate properties of an object format
  60 such as its file representation, ELF class, and byte endianness.
  61 .Pp
  62 Known descriptor names and their properties include:
  63 .Bl -column -offset "XXXX" ".Li elf32-x86-64-freebsd" "Object format" "Byte Order" "Bit Width"
  64 .It Em Name Ta Em "Object Format" Ta Em "Byte Order" Ta Em "Bit Width"
  65 .It Li binary Ta Binary Ta - Ta -
  66 .It Li efi-app-ia32 Ta PE Ta LSB Ta 32
  67 .It Li efi-app-x86_64 Ta PE Ta LSB Ta 64
  68 .It Li elf32-avr Ta ELF Ta LSB Ta 32
  69 .It Li elf32-big Ta ELF Ta MSB Ta 32
  70 .It Li elf32-bigarm Ta ELF Ta MSB Ta 32
  71 .It Li elf32-bigmips Ta ELF Ta MSB Ta 32
  72 .It Li elf32-i386 Ta ELF Ta LSB Ta 32
  73 .It Li elf32-i386-freebsd Ta ELF Ta LSB Ta 32
  74 .It Li elf32-ia64-big Ta ELF Ta MSB Ta 32
  75 .It Li elf32-little Ta ELF Ta LSB Ta 32
  76 .It Li elf32-littlearm Ta ELF Ta LSB Ta 32
  77 .It Li elf32-littlemips Ta ELF Ta LSB Ta 32
  78 .It Li elf32-powerpc Ta ELF Ta MSB Ta 32
  79 .It Li elf32-powerpc-freebsd Ta ELF Ta MSB Ta 32
  80 .It Li elf32-powerpcle Ta ELF Ta LSB Ta 32
  81 .It Li elf32-riscv Ta ELF Ta LSB Ta 32
  82 .It Li elf64-riscv Ta ELF Ta LSB Ta 64
  83 .It Li elf64-riscv-freebsd Ta ELF Ta LSB Ta 64
  84 .It Li elf32-sh Ta ELF Ta MSB Ta 32
  85 .It Li elf32-shl Ta ELF Ta LSB Ta 32
  86 .It Li elf32-sh-nbsd Ta ELF Ta MSB Ta 32
  87 .It Li elf32-shl-nbsd Ta ELF Ta LSB Ta 32
  88 .It Li elf32-shbig-linux Ta ELF Ta MSB Ta 32
  89 .It Li elf32-shl-linux Ta ELF Ta LSB Ta 32
  90 .It Li elf32-sparc Ta ELF Ta MSB Ta 32
  91 .It Li elf32-tradbigmips Ta ELF Ta MSB Ta 32
  92 .It Li elf32-tradlittlemips Ta ELF Ta LSB Ta 32
  93 .It Li elf64-alpha Ta ELF Ta LSB Ta 64
  94 .It Li elf64-alpha-freebsd Ta ELF Ta LSB Ta 64
  95 .It Li elf64-big Ta ELF Ta MSB Ta 64
  96 .It Li elf64-bigmips Ta ELF Ta MSB Ta 64
  97 .It Li elf64-ia64-big Ta ELF Ta MSB Ta 64
  98 .It Li elf64-ia64-little Ta ELF Ta LSB Ta 64
  99 .It Li elf64-little Ta ELF Ta LSB Ta 64
 100 .It Li elf64-littleaarch64 Ta ELF Ta LSB Ta 64
 101 .It Li elf64-littlemips Ta ELF Ta LSB Ta 64
 102 .It Li elf64-powerpc Ta ELF Ta MSB Ta 64
 103 .It Li elf64-powerpc-freebsd Ta ELF Ta MSB Ta 64
 104 .It Li elf64-powerpcle Ta ELF Ta LSB Ta 64
 105 .It Li elf64-sh64 Ta ELF Ta MSB Ta 64
 106 .It Li elf64-sh64l Ta ELF Ta LSB Ta 64
 107 .It Li elf64-sh64-nbsd Ta ELF Ta MSB Ta 64
 108 .It Li elf64-sh64l-nbsd Ta ELF Ta LSB Ta 64
 109 .It Li elf64-sh64big-linux Ta ELF Ta MSB Ta 64
 110 .It Li elf64-sh64-linux Ta ELF Ta LSB Ta 64
 111 .It Li elf64-sparc Ta ELF Ta MSB Ta 64
 112 .It Li elf64-sparc-freebsd Ta ELF Ta MSB Ta 64
 113 .It Li elf64-tradbigmips Ta ELF Ta MSB Ta 64
 114 .It Li elf64-tradlittlemips Ta ELF Ta LSB Ta 64
 115 .It Li elf64-x86-64 Ta ELF Ta LSB Ta 64
 116 .It Li elf64-x86-64-freebsd Ta ELF Ta LSB Ta 64
 117 .It Li ihex Ta IHEX Ta - Ta -
 118 .It Li pei-i386 Ta PE Ta LSB Ta 32
 119 .It Li pei-x86-64 Ta PE Ta LSB Ta 64
 120 .It Li srec Ta SREC Ta - Ta -
 121 .It Li symbolsrec Ta SREC Ta - Ta -
 122 .El
 123 .Pp
 124 Function
 125 .Fn elftc_bfd_target_byteorder
 126 returns the ELF byte order associated with target descriptor
 127 .Ar target .
 128 .Pp
 129 Function
 130 .Fn elftc_bfd_target_class
 131 returns the ELF class associated with target descriptor
 132 .Ar target .
 133 .Pp
 134 Function
 135 .Fn elftc_bfd_target_flavor
 136 returns the object format associated with target descriptor
 137 .Ar target .
 138 The known object formats are:
 139 .Bl -tag -offset "XXXX" -width ".Dv ETF_BINARY" -compact
 140 .It Dv ETF_ELF
 141 An ELF object.
 142 .It Dv ETF_BINARY
 143 Raw binary.
 144 .It Dv ETF_IHEX
 145 An object encoded in
 146 .Tn Intel
 147 hex format.
 148 .It Dv ETF_NONE
 149 An unknown object format.
 150 .It Dv ETF_SREC
 151 An object encoded as S-records.
 152 .El
 153 .Sh RETURN VALUES
 154 Function
 155 .Fn elftc_bfd_find_target
 156 returns a valid pointer to an opaque binary target descriptor if
 157 successful, or NULL in case of an error.
 158 .Pp
 159 Function
 160 .Fn elftc_bfd_target_byteorder
 161 returns the ELF byte order associated with the target descriptor; one of
 162 .Dv ELFDATA2MSB
 163 or
 164 .Dv ELFDATA2LSB .
 165 .Pp
 166 Function
 167 .Fn elftc_bfd_target_class
 168 returns the ELF class associated with the target descriptor; one of
 169 .Dv ELFCLASS32
 170 or
 171 .Dv ELFCLASS64 .
 172 .Pp
 173 Function
 174 .Fn elftc_bfd_target_machine
 175 returns the ELF architecture associated with the target descriptor.
 176 .Pp
 177 Function
 178 .Fn elftc_bfd_target_flavor
 179 returns one of
 180 .Dv ETF_BINARY ,
 181 .Dv ETF_ELF ,
 182 .Dv ETF_IHEX
 183 or
 184 .Dv ETF_SREC
 185 if successful or
 186 .Dv ETF_NONE
 187 in case of error.
 188 .Sh EXAMPLES
 189 To return descriptor information associated with target name
 190 .Dq elf64-big
 191 use:
 192 .Bd -literal -offset indent
 193 struct Elftc_Bfd_Target *t;
 194
 195 if ((t = elftc_bfd_find_target("elf64-big")) == NULL)
 196         errx(EXIT_FAILURE, "Cannot find target descriptor");
 197
 198 printf("Class: %s\\n", elftc_bfd_target_class(t) == ELFCLASS32 ?
 199     "ELFCLASS32" : "ELFCLASS64");
 200 printf("Byteorder: %s\\n",
 201     elftc_bfd_target_byteorder(t) == ELFDATA2LSB ? "LSB" : "MSB");
 202 printf("Flavor: %d\\n", elftc_bfd_target_flavor(t));
 203 .Ed
 204 .Sh SEE ALSO
 205 .Xr elf 3