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