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