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
54Function
55.Fn elftc_bfd_find_target
56locates a binary object descriptor corresponding to the descriptor
57name in argument
58.Ar "target_name" .
59Binary object descriptors encapsulate properties of an object format
60such as its file representation, ELF class, and byte endianness.
61.Pp
62Known 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
124Function
125.Fn elftc_bfd_target_byteorder
126returns the ELF byte order associated with target descriptor
127.Ar target .
128.Pp
129Function
130.Fn elftc_bfd_target_class
131returns the ELF class associated with target descriptor
132.Ar target .
133.Pp
134Function
135.Fn elftc_bfd_target_flavor
136returns the object format associated with target descriptor
137.Ar target .
138The known object formats are:
139.Bl -tag -offset "XXXX" -width ".Dv ETF_BINARY" -compact
140.It Dv ETF_ELF
141An ELF object.
142.It Dv ETF_BINARY
143Raw binary.
144.It Dv ETF_IHEX
145An object encoded in
146.Tn Intel
147hex format.
148.It Dv ETF_NONE
149An unknown object format.
150.It Dv ETF_SREC
151An object encoded as S-records.
152.El
153.Sh RETURN VALUES
154Function
155.Fn elftc_bfd_find_target
156returns a valid pointer to an opaque binary target descriptor if
157successful, or NULL in case of an error.
158.Pp
159Function
160.Fn elftc_bfd_target_byteorder
161returns the ELF byte order associated with the target descriptor; one of
162.Dv ELFDATA2MSB
163or
164.Dv ELFDATA2LSB .
165.Pp
166Function
167.Fn elftc_bfd_target_class
168returns the ELF class associated with the target descriptor; one of
169.Dv ELFCLASS32
170or
171.Dv ELFCLASS64 .
172.Pp
173Function
174.Fn elftc_bfd_target_machine
175returns the ELF architecture associated with the target descriptor.
176.Pp
177Function
178.Fn elftc_bfd_target_flavor
179returns one of
180.Dv ETF_BINARY ,
181.Dv ETF_ELF ,
182.Dv ETF_IHEX
183or
184.Dv ETF_SREC
185if successful or
186.Dv ETF_NONE
187in case of error.
188.Sh EXAMPLES
189To return descriptor information associated with target name
190.Dq elf64-big
191use:
192.Bd -literal -offset indent
193struct Elftc_Bfd_Target *t;
194
195if ((t = elftc_bfd_find_target("elf64-big")) == NULL)
196	errx(EXIT_FAILURE, "Cannot find target descriptor");
197
198printf("Class: %s\\n", elftc_bfd_target_class(t) == ELFCLASS32 ?
199    "ELFCLASS32" : "ELFCLASS64");
200printf("Byteorder: %s\\n",
201    elftc_bfd_target_byteorder(t) == ELFDATA2LSB ? "LSB" : "MSB");
202printf("Flavor: %d\\n", elftc_bfd_target_flavor(t));
203.Ed
204.Sh SEE ALSO
205.Xr elf 3
206