1*a1b5ec25Sjsg.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. 2*a1b5ec25Sjsg.\" 3*a1b5ec25Sjsg.\" Redistribution and use in source and binary forms, with or without 4*a1b5ec25Sjsg.\" modification, are permitted provided that the following conditions 5*a1b5ec25Sjsg.\" are met: 6*a1b5ec25Sjsg.\" 1. Redistributions of source code must retain the above copyright 7*a1b5ec25Sjsg.\" notice, this list of conditions and the following disclaimer. 8*a1b5ec25Sjsg.\" 2. Redistributions in binary form must reproduce the above copyright 9*a1b5ec25Sjsg.\" notice, this list of conditions and the following disclaimer in the 10*a1b5ec25Sjsg.\" documentation and/or other materials provided with the distribution. 11*a1b5ec25Sjsg.\" 12*a1b5ec25Sjsg.\" This software is provided by Joseph Koshy ``as is'' and 13*a1b5ec25Sjsg.\" any express or implied warranties, including, but not limited to, the 14*a1b5ec25Sjsg.\" implied warranties of merchantability and fitness for a particular purpose 15*a1b5ec25Sjsg.\" are disclaimed. in no event shall Joseph Koshy be liable 16*a1b5ec25Sjsg.\" for any direct, indirect, incidental, special, exemplary, or consequential 17*a1b5ec25Sjsg.\" damages (including, but not limited to, procurement of substitute goods 18*a1b5ec25Sjsg.\" or services; loss of use, data, or profits; or business interruption) 19*a1b5ec25Sjsg.\" however caused and on any theory of liability, whether in contract, strict 20*a1b5ec25Sjsg.\" liability, or tort (including negligence or otherwise) arising in any way 21*a1b5ec25Sjsg.\" out of the use of this software, even if advised of the possibility of 22*a1b5ec25Sjsg.\" such damage. 23*a1b5ec25Sjsg.\" 24*a1b5ec25Sjsg.\" $Id: elf_errmsg.3,v 1.1 2019/02/01 05:27:37 jsg Exp $ 25*a1b5ec25Sjsg.\" 26*a1b5ec25Sjsg.Dd June 11, 2006 27*a1b5ec25Sjsg.Dt ELF_ERRMSG 3 28*a1b5ec25Sjsg.Os 29*a1b5ec25Sjsg.Sh NAME 30*a1b5ec25Sjsg.Nm elf_errmsg , 31*a1b5ec25Sjsg.Nm elf_errno 32*a1b5ec25Sjsg.Nd ELF library error message handling 33*a1b5ec25Sjsg.Sh LIBRARY 34*a1b5ec25Sjsg.Lb libelf 35*a1b5ec25Sjsg.Sh SYNOPSIS 36*a1b5ec25Sjsg.In libelf.h 37*a1b5ec25Sjsg.Ft int 38*a1b5ec25Sjsg.Fn elf_errno "void" 39*a1b5ec25Sjsg.Ft "const char *" 40*a1b5ec25Sjsg.Fn elf_errmsg "int error" 41*a1b5ec25Sjsg.Sh DESCRIPTION 42*a1b5ec25SjsgWhen an error occurs during an ELF library API call, the library 43*a1b5ec25Sjsgencodes the error using an error number and stores the error number 44*a1b5ec25Sjsginternally for retrieval by the application at a later point of time. 45*a1b5ec25SjsgError numbers may contain an OS supplied error code in addition to 46*a1b5ec25Sjsgan ELF API specific error code. 47*a1b5ec25SjsgAn error number value of zero indicates no error. 48*a1b5ec25Sjsg.Pp 49*a1b5ec25SjsgFunction 50*a1b5ec25Sjsg.Fn elf_errno 51*a1b5ec25Sjsgis used to retrieve the last error recorded by the ELF library. 52*a1b5ec25SjsgInvoking this function has the side-effect of resetting the 53*a1b5ec25SjsgELF library's recorded error number to zero. 54*a1b5ec25Sjsg.Pp 55*a1b5ec25SjsgThe function 56*a1b5ec25Sjsg.Fn elf_errmsg 57*a1b5ec25Sjsgreturns a null-terminated string with a human readable 58*a1b5ec25Sjsgdescription of the error specified in argument 59*a1b5ec25Sjsg.Ar error . 60*a1b5ec25SjsgA zero value for argument 61*a1b5ec25Sjsg.Ar error 62*a1b5ec25Sjsgretrieves the most recent error encountered by the ELF 63*a1b5ec25Sjsglibrary. 64*a1b5ec25SjsgAn argument value of -1 behaves identically, except that 65*a1b5ec25Sjsgit guarantees a non-NULL return from 66*a1b5ec25Sjsg.Fn elf_errmsg . 67*a1b5ec25Sjsg.Sh RETURN VALUES 68*a1b5ec25SjsgFunction 69*a1b5ec25Sjsg.Fn elf_errno 70*a1b5ec25Sjsgreturns a non-zero value encoding the last error encountered 71*a1b5ec25Sjsgby the ELF library, or zero if no error was encountered. 72*a1b5ec25Sjsg.Pp 73*a1b5ec25SjsgFunction 74*a1b5ec25Sjsg.Fn elf_errmsg 75*a1b5ec25Sjsgreturns a pointer to library local storage for non-zero values 76*a1b5ec25Sjsgof argument 77*a1b5ec25Sjsg.Ar error . 78*a1b5ec25SjsgWith a zero argument, the function will return a NULL pointer if no 79*a1b5ec25Sjsgerror had been encountered by the library, or will return a pointer to 80*a1b5ec25Sjsglibrary local storage containing an appropriate message otherwise. 81*a1b5ec25Sjsg.Sh EXAMPLES 82*a1b5ec25SjsgClearing the ELF library's recorded error number can be accomplished 83*a1b5ec25Sjsgby invoking 84*a1b5ec25Sjsg.Fn elf_errno 85*a1b5ec25Sjsgand discarding its return value. 86*a1b5ec25Sjsg.Bd -literal -offset indent 87*a1b5ec25Sjsg/* clear error */ 88*a1b5ec25Sjsg(void) elf_errno(); 89*a1b5ec25Sjsg.Ed 90*a1b5ec25Sjsg.Pp 91*a1b5ec25SjsgRetrieving a human-readable description of the current error number 92*a1b5ec25Sjsgcan be done with the following snippet: 93*a1b5ec25Sjsg.Bd -literal -offset indent 94*a1b5ec25Sjsgint err; 95*a1b5ec25Sjsgconst char *errmsg; 96*a1b5ec25Sjsg\&... 97*a1b5ec25Sjsgerr = elf_errno(); 98*a1b5ec25Sjsgif (err != 0) 99*a1b5ec25Sjsg errmsg = elf_errmsg(err); 100*a1b5ec25Sjsg.Ed 101*a1b5ec25Sjsg.Sh SEE ALSO 102*a1b5ec25Sjsg.Xr elf 3 , 103*a1b5ec25Sjsg.Xr gelf 3 104*a1b5ec25Sjsg.Sh BUGS 105*a1b5ec25SjsgFunction 106*a1b5ec25Sjsg.Fn elf_errmsg 107*a1b5ec25Sjsgis not localized. 108