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