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