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 2251 2011-11-30 16:50:06Z jkoshy $
  25 .\"
  26 .Dd November 30, 2011
  27 .Os
  28 .Dt ELFTC_BFD_FIND_TARGET
  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" "ELF Class"
  62 .It Em Name Ta Em "Object Format" Ta Em "Byte Order" Ta Em "ELF Class"
  63 .It Li binary Ta Binary Ta - Ta -
  64 .It Li elf32-avr Ta ELF Ta LSB Ta 32
  65 .It Li elf32-big Ta ELF Ta MSB Ta 32
  66 .It Li elf32-bigarm Ta ELF Ta MSB Ta 32
  67 .It Li elf32-bigmips Ta ELF Ta MSB Ta 32
  68 .It Li elf32-i386 Ta ELF Ta LSB Ta 32
  69 .It Li elf32-i386-freebsd Ta ELF Ta LSB Ta 32
  70 .It Li elf32-ia64-big Ta ELF Ta MSB Ta 32
  71 .It Li elf32-little Ta ELF Ta LSB Ta 32
  72 .It Li elf32-littlearm Ta ELF Ta LSB Ta 32
  73 .It Li elf32-littlemips Ta ELF Ta LSB Ta 32
  74 .It Li elf32-powerpc Ta ELF Ta MSB Ta 32
  75 .It Li elf32-powerpcle Ta ELF Ta LSB Ta 32
  76 .It Li elf32-sh Ta ELF Ta MSB Ta 32
  77 .It Li elf32-shl Ta ELF Ta LSB Ta 32
  78 .It Li elf32-sh-nbsd Ta ELF Ta MSB Ta 32
  79 .It Li elf32-shl-nbsd Ta ELF Ta LSB Ta 32
  80 .It Li elf32-shbig-linux Ta ELF Ta MSB Ta 32
  81 .It Li elf32-shl-linux Ta ELF Ta LSB Ta 32
  82 .It Li elf32-sparc Ta ELF Ta MSB Ta 32
  83 .It Li elf64-alpha Ta ELF Ta LSB Ta 64
  84 .It Li elf64-alpha-freebsd Ta ELF Ta LSB Ta 64
  85 .It Li elf64-big Ta ELF Ta MSB Ta 64
  86 .It Li elf64-bigmips Ta ELF Ta MSB Ta 64
  87 .It Li elf64-ia64-big Ta ELF Ta MSB Ta 64
  88 .It Li elf64-ia64-little Ta ELF Ta LSB Ta 64
  89 .It Li elf64-little Ta ELF Ta LSB Ta 64
  90 .It Li elf64-littlemips Ta ELF Ta LSB Ta 64
  91 .It Li elf64-powerpc Ta ELF Ta MSB Ta 64
  92 .It Li elf64-powerpcle Ta ELF Ta LSB Ta 64
  93 .It Li elf64-sh64 Ta ELF Ta MSB Ta 64
  94 .It Li elf64-sh64l Ta ELF Ta LSB Ta 64
  95 .It Li elf64-sh64-nbsd Ta ELF Ta MSB Ta 64
  96 .It Li elf64-sh64l-nbsd Ta ELF Ta LSB Ta 64
  97 .It Li elf64-sh64big-linux Ta ELF Ta MSB Ta 64
  98 .It Li elf64-sh64-linux Ta ELF Ta LSB Ta 64
  99 .It Li elf64-sparc Ta ELF Ta MSB Ta 64
 100 .It Li elf64-sparc-freebsd Ta ELF Ta MSB Ta 64
 101 .It Li elf64-x86-64 Ta ELF Ta LSB Ta 64
 102 .It Li elf64-x86-64-freebsd Ta ELF Ta LSB Ta 64
 103 .It Li ihex Ta IHEX Ta - Ta -
 104 .It Li srec Ta SREC Ta - Ta -
 105 .It Li symbolsrec Ta SREC Ta - Ta -
 106 .El
 107 .Pp
 108 Function
 109 .Fn elftc_bfd_target_byteorder
 110 returns the ELF byte order associated with target descriptor
 111 .Ar target .
 112 .Pp
 113 Function
 114 .Fn elftc_bfd_target_class
 115 returns the ELF class associated with target descriptor
 116 .Ar target .
 117 .Pp
 118 Function
 119 .Fn elftc_bfd_target_flavor
 120 returns the object format associated with target descriptor
 121 .Ar target .
 122 The known object formats are:
 123 .Bl -tag -offset "XXXX" -width ".Dv ETF_BINARY" -compact
 124 .It Dv ETF_ELF
 125 An ELF object.
 126 .It Dv ETF_BINARY
 127 Raw binary.
 128 .It Dv ETF_IHEX
 129 An object encoded in
 130 .Tn Intel
 131 hex format.
 132 .It Dv ETF_NONE
 133 An unknown object format.
 134 .It Dv ETF_SREC
 135 An object encoded as S-records.
 136 .El
 137 .Sh RETURN VALUES
 138 Function
 139 .Fn elftc_bfd_find_target
 140 returns a valid pointer to an opaque binary target descriptor if
 141 successful, or NULL in case of an error.
 142 .Pp
 143 Function
 144 .Fn elftc_bfd_target_byteorder
 145 returns the ELF byte order associated with the target descriptor; one of
 146 .Dv ELFDATA2MSB
 147 or
 148 .Dv ELFDATA2LSB .
 149 .Pp
 150 Function
 151 .Fn elftc_bfd_target_class
 152 returns the ELF class associated with the target descriptor; one of
 153 .Dv ELFCLASS32
 154 or
 155 .Dv ELFCLASS64 .
 156 .Pp
 157 Function
 158 .Fn elftc_bfd_target_machine
 159 returns the ELF architecture associated with the target descriptor.
 160 .Pp
 161 Function
 162 .Fn elftc_bfd_target_flavor
 163 returns one of
 164 .Dv ETF_BINARY ,
 165 .Dv ETF_ELF ,
 166 .Dv ETF_IHEX
 167 or
 168 .Dv ETF_SREC
 169 if successful or
 170 .Dv ETF_NONE
 171 in case of error.
 172 .Sh EXAMPLES
 173 To return descriptor information associated with target name
 174 .Dq elf64-big
 175 use:
 176 .Bd -literal -offset indent
 177 struct Elftc_Bfd_Target *t;
 178
 179 if ((t = elftc_bfd_find_target("elf64-big")) == NULL)
 180         errx(EXIT_FAILURE, "Cannot find target descriptor");
 181
 182 printf("Class: %s\\n", elftc_bfd_target_class(t) == ELFCLASS32 ?
 183     "ELFCLASS32" : "ELFCLASS64");
 184 printf("Byteorder: %s\\n",
 185     elftc_bfd_target_byteorder(t) == ELFDATA2LSB ? "LSB" : "MSB");
 186 printf("Flavor: %d\\n", elftc_bfd_target_flavor(t));
 187 .Ed
 188 .Sh SEE ALSO
 189 .Xr elf 3