Error-reporting.html 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- This file documents the BFD library.
  4. Copyright (C) 1991-2017 Free Software Foundation, Inc.
  5. Permission is granted to copy, distribute and/or modify this document
  6. under the terms of the GNU Free Documentation License, Version 1.3 or
  7. any later version published by the Free Software Foundation; with the
  8. Invariant Sections being "GNU General Public License" and "Funding
  9. Free Software", the Front-Cover texts being (a) (see below), and with
  10. the Back-Cover Texts being (b) (see below). A copy of the license is
  11. included in the section entitled "GNU Free Documentation License".
  12. (a) The FSF's Front-Cover Text is:
  13. A GNU Manual
  14. (b) The FSF's Back-Cover Text is:
  15. You have freedom to copy and modify this GNU Manual, like GNU
  16. software. Copies published by the Free Software Foundation raise
  17. funds for GNU development. -->
  18. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  19. <head>
  20. <title>Untitled Document: Error reporting</title>
  21. <meta name="description" content="Untitled Document: Error reporting">
  22. <meta name="keywords" content="Untitled Document: Error reporting">
  23. <meta name="resource-type" content="document">
  24. <meta name="distribution" content="global">
  25. <meta name="Generator" content="makeinfo">
  26. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  27. <link href="index.html#Top" rel="start" title="Top">
  28. <link href="BFD-Index.html#BFD-Index" rel="index" title="BFD Index">
  29. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  30. <link href="BFD-front-end.html#BFD-front-end" rel="up" title="BFD front end">
  31. <link href="Miscellaneous.html#Miscellaneous" rel="next" title="Miscellaneous">
  32. <link href="typedef-bfd.html#typedef-bfd" rel="prev" title="typedef bfd">
  33. <style type="text/css">
  34. <!--
  35. a.summary-letter {text-decoration: none}
  36. blockquote.smallquotation {font-size: smaller}
  37. div.display {margin-left: 3.2em}
  38. div.example {margin-left: 3.2em}
  39. div.indentedblock {margin-left: 3.2em}
  40. div.lisp {margin-left: 3.2em}
  41. div.smalldisplay {margin-left: 3.2em}
  42. div.smallexample {margin-left: 3.2em}
  43. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  44. div.smalllisp {margin-left: 3.2em}
  45. kbd {font-style:oblique}
  46. pre.display {font-family: inherit}
  47. pre.format {font-family: inherit}
  48. pre.menu-comment {font-family: serif}
  49. pre.menu-preformatted {font-family: serif}
  50. pre.smalldisplay {font-family: inherit; font-size: smaller}
  51. pre.smallexample {font-size: smaller}
  52. pre.smallformat {font-family: inherit; font-size: smaller}
  53. pre.smalllisp {font-size: smaller}
  54. span.nocodebreak {white-space:nowrap}
  55. span.nolinebreak {white-space:nowrap}
  56. span.roman {font-family:serif; font-weight:normal}
  57. span.sansserif {font-family:sans-serif; font-weight:normal}
  58. ul.no-bullet {list-style: none}
  59. -->
  60. </style>
  61. </head>
  62. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  63. <a name="Error-reporting"></a>
  64. <div class="header">
  65. <p>
  66. Next: <a href="Miscellaneous.html#Miscellaneous" accesskey="n" rel="next">Miscellaneous</a>, Previous: <a href="typedef-bfd.html#typedef-bfd" accesskey="p" rel="prev">typedef bfd</a>, Up: <a href="BFD-front-end.html#BFD-front-end" accesskey="u" rel="up">BFD front end</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="BFD-Index.html#BFD-Index" title="Index" rel="index">Index</a>]</p>
  67. </div>
  68. <hr>
  69. <a name="Error-reporting-1"></a>
  70. <h3 class="section">2.2 Error reporting</h3>
  71. <p>Most BFD functions return nonzero on success (check their
  72. individual documentation for precise semantics). On an error,
  73. they call <code>bfd_set_error</code> to set an error condition that callers
  74. can check by calling <code>bfd_get_error</code>.
  75. If that returns <code>bfd_error_system_call</code>, then check
  76. <code>errno</code>.
  77. </p>
  78. <p>The easiest way to report a BFD error to the user is to
  79. use <code>bfd_perror</code>.
  80. </p>
  81. <a name="Type-bfd_005ferror_005ftype"></a>
  82. <h4 class="subsection">2.2.1 Type <code>bfd_error_type</code></h4>
  83. <p>The values returned by <code>bfd_get_error</code> are defined by the
  84. enumerated type <code>bfd_error_type</code>.
  85. </p>
  86. <div class="example">
  87. <pre class="example">
  88. typedef enum bfd_error
  89. {
  90. bfd_error_no_error = 0,
  91. bfd_error_system_call,
  92. bfd_error_invalid_target,
  93. bfd_error_wrong_format,
  94. bfd_error_wrong_object_format,
  95. bfd_error_invalid_operation,
  96. bfd_error_no_memory,
  97. bfd_error_no_symbols,
  98. bfd_error_no_armap,
  99. bfd_error_no_more_archived_files,
  100. bfd_error_malformed_archive,
  101. bfd_error_missing_dso,
  102. bfd_error_file_not_recognized,
  103. bfd_error_file_ambiguously_recognized,
  104. bfd_error_no_contents,
  105. bfd_error_nonrepresentable_section,
  106. bfd_error_no_debug_section,
  107. bfd_error_bad_value,
  108. bfd_error_file_truncated,
  109. bfd_error_file_too_big,
  110. bfd_error_on_input,
  111. bfd_error_invalid_error_code
  112. }
  113. bfd_error_type;
  114. </pre></div>
  115. <a name="index-bfd_005fget_005ferror"></a>
  116. <a name="bfd_005fget_005ferror"></a>
  117. <h4 class="subsubsection">2.2.1.1 <code>bfd_get_error</code></h4>
  118. <p><strong>Synopsis</strong>
  119. </p><div class="example">
  120. <pre class="example">bfd_error_type bfd_get_error (void);
  121. </pre></div>
  122. <p><strong>Description</strong><br>
  123. Return the current BFD error condition.
  124. </p>
  125. <a name="index-bfd_005fset_005ferror"></a>
  126. <a name="bfd_005fset_005ferror"></a>
  127. <h4 class="subsubsection">2.2.1.2 <code>bfd_set_error</code></h4>
  128. <p><strong>Synopsis</strong>
  129. </p><div class="example">
  130. <pre class="example">void bfd_set_error (bfd_error_type error_tag, ...);
  131. </pre></div>
  132. <p><strong>Description</strong><br>
  133. Set the BFD error condition to be <var>error_tag</var>.
  134. If <var>error_tag</var> is bfd_error_on_input, then this function
  135. takes two more parameters, the input bfd where the error
  136. occurred, and the bfd_error_type error.
  137. </p>
  138. <a name="index-bfd_005ferrmsg"></a>
  139. <a name="bfd_005ferrmsg"></a>
  140. <h4 class="subsubsection">2.2.1.3 <code>bfd_errmsg</code></h4>
  141. <p><strong>Synopsis</strong>
  142. </p><div class="example">
  143. <pre class="example">const char *bfd_errmsg (bfd_error_type error_tag);
  144. </pre></div>
  145. <p><strong>Description</strong><br>
  146. Return a string describing the error <var>error_tag</var>, or
  147. the system error if <var>error_tag</var> is <code>bfd_error_system_call</code>.
  148. </p>
  149. <a name="index-bfd_005fperror"></a>
  150. <a name="bfd_005fperror"></a>
  151. <h4 class="subsubsection">2.2.1.4 <code>bfd_perror</code></h4>
  152. <p><strong>Synopsis</strong>
  153. </p><div class="example">
  154. <pre class="example">void bfd_perror (const char *message);
  155. </pre></div>
  156. <p><strong>Description</strong><br>
  157. Print to the standard error stream a string describing the
  158. last BFD error that occurred, or the last system error if
  159. the last BFD error was a system call failure. If <var>message</var>
  160. is non-NULL and non-empty, the error string printed is preceded
  161. by <var>message</var>, a colon, and a space. It is followed by a newline.
  162. </p>
  163. <a name="BFD-error-handler"></a>
  164. <h4 class="subsection">2.2.2 BFD error handler</h4>
  165. <p>Some BFD functions want to print messages describing the
  166. problem. They call a BFD error handler function. This
  167. function may be overridden by the program.
  168. </p>
  169. <p>The BFD error handler acts like vprintf.
  170. </p>
  171. <div class="example">
  172. <pre class="example">
  173. typedef void (*bfd_error_handler_type) (const char *, va_list);
  174. </pre></div>
  175. <a name="index-bfd_005fset_005ferror_005fhandler"></a>
  176. <a name="bfd_005fset_005ferror_005fhandler"></a>
  177. <h4 class="subsubsection">2.2.2.1 <code>bfd_set_error_handler</code></h4>
  178. <p><strong>Synopsis</strong>
  179. </p><div class="example">
  180. <pre class="example">bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);
  181. </pre></div>
  182. <p><strong>Description</strong><br>
  183. Set the BFD error handler function. Returns the previous
  184. function.
  185. </p>
  186. <a name="index-bfd_005fset_005ferror_005fprogram_005fname"></a>
  187. <a name="bfd_005fset_005ferror_005fprogram_005fname"></a>
  188. <h4 class="subsubsection">2.2.2.2 <code>bfd_set_error_program_name</code></h4>
  189. <p><strong>Synopsis</strong>
  190. </p><div class="example">
  191. <pre class="example">void bfd_set_error_program_name (const char *);
  192. </pre></div>
  193. <p><strong>Description</strong><br>
  194. Set the program name to use when printing a BFD error. This
  195. is printed before the error message followed by a colon and
  196. space. The string must not be changed after it is passed to
  197. this function.
  198. </p>
  199. <a name="BFD-assert-handler"></a>
  200. <h4 class="subsection">2.2.3 BFD assert handler</h4>
  201. <p>If BFD finds an internal inconsistency, the bfd assert
  202. handler is called with information on the BFD version, BFD
  203. source file and line. If this happens, most programs linked
  204. against BFD are expected to want to exit with an error, or mark
  205. the current BFD operation as failed, so it is recommended to
  206. override the default handler, which just calls
  207. _bfd_error_handler and continues.
  208. </p>
  209. <div class="example">
  210. <pre class="example">
  211. typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg,
  212. const char *bfd_version,
  213. const char *bfd_file,
  214. int bfd_line);
  215. </pre></div>
  216. <a name="index-bfd_005fset_005fassert_005fhandler"></a>
  217. <a name="bfd_005fset_005fassert_005fhandler"></a>
  218. <h4 class="subsubsection">2.2.3.1 <code>bfd_set_assert_handler</code></h4>
  219. <p><strong>Synopsis</strong>
  220. </p><div class="example">
  221. <pre class="example">bfd_assert_handler_type bfd_set_assert_handler (bfd_assert_handler_type);
  222. </pre></div>
  223. <p><strong>Description</strong><br>
  224. Set the BFD assert handler function. Returns the previous
  225. function.
  226. </p>
  227. <hr>
  228. <div class="header">
  229. <p>
  230. Next: <a href="Miscellaneous.html#Miscellaneous" accesskey="n" rel="next">Miscellaneous</a>, Previous: <a href="typedef-bfd.html#typedef-bfd" accesskey="p" rel="prev">typedef bfd</a>, Up: <a href="BFD-front-end.html#BFD-front-end" accesskey="u" rel="up">BFD front end</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="BFD-Index.html#BFD-Index" title="Index" rel="index">Index</a>]</p>
  231. </div>
  232. </body>
  233. </html>