xref: /freebsd/contrib/elftoolchain/libelf/elf_errmsg.3 (revision 95ee2897e98f5d444f26ed2334cc7c439f9c16c6)
1.\" Copyright (c) 2006,2008 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: elf_errmsg.3 3639 2018-10-14 14:07:02Z jkoshy $
25.\"
26.Dd June 11, 2006
27.Dt ELF_ERRMSG 3
28.Os
29.Sh NAME
30.Nm elf_errmsg ,
31.Nm elf_errno
32.Nd ELF library error message handling
33.Sh LIBRARY
34.Lb libelf
35.Sh SYNOPSIS
36.In libelf.h
37.Ft int
38.Fn elf_errno "void"
39.Ft "const char *"
40.Fn elf_errmsg "int error"
41.Sh DESCRIPTION
42When an error occurs during an ELF library API call, the library
43encodes the error using an error number and stores the error number
44internally for retrieval by the application at a later point of time.
45Error numbers may contain an OS supplied error code in addition to
46an ELF API specific error code.
47An error number value of zero indicates no error.
48.Pp
49Function
50.Fn elf_errno
51is used to retrieve the last error recorded by the ELF library.
52Invoking this function has the side-effect of resetting the
53ELF library's recorded error number to zero.
54.Pp
55The function
56.Fn elf_errmsg
57returns a null-terminated string with a human readable
58description of the error specified in argument
59.Ar error .
60A zero value for argument
61.Ar error
62retrieves the most recent error encountered by the ELF
63library.
64An argument value of -1 behaves identically, except that
65it guarantees a non-NULL return from
66.Fn elf_errmsg .
67.Sh RETURN VALUES
68Function
69.Fn elf_errno
70returns a non-zero value encoding the last error encountered
71by the ELF library, or zero if no error was encountered.
72.Pp
73Function
74.Fn elf_errmsg
75returns a pointer to library local storage for non-zero values
76of argument
77.Ar error .
78With a zero argument, the function will return a NULL pointer if no
79error had been encountered by the library, or will return a pointer to
80library local storage containing an appropriate message otherwise.
81.Sh EXAMPLES
82Clearing the ELF library's recorded error number can be accomplished
83by invoking
84.Fn elf_errno
85and discarding its return value.
86.Bd -literal -offset indent
87/* clear error */
88(void) elf_errno();
89.Ed
90.Pp
91Retrieving a human-readable description of the current error number
92can be done with the following snippet:
93.Bd -literal -offset indent
94int err;
95const char *errmsg;
96\&...
97err = elf_errno();
98if (err != 0)
99	errmsg = elf_errmsg(err);
100.Ed
101.Sh SEE ALSO
102.Xr elf 3 ,
103.Xr gelf 3
104.Sh BUGS
105Function
106.Fn elf_errmsg
107is not localized.
108