Home | History | Annotate | Line # | Download | only in isc 
      1 /*	$NetBSD: backtrace.h,v 1.7 2025/01/26 16:25:40 christos Exp $	*/
      2 
      3 /*
      4  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
      5  *
      6  * SPDX-License-Identifier: MPL-2.0
      7  *
      8  * This Source Code Form is subject to the terms of the Mozilla Public
      9  * License, v. 2.0. If a copy of the MPL was not distributed with this
     10  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
     11  *
     12  * See the COPYRIGHT file distributed with this work for additional
     13  * information regarding copyright ownership.
     14  */
     15 
     16 /*! \file isc/backtrace.h
     17  * \brief provide a back trace of the running process to help debug problems.
     18  *
     19  * This module tries to get a back trace of the process using some platform
     20  * dependent way when available.  It also manages an internal symbol table
     21  * that maps function addresses used in the process to their textual symbols.
     22  * This module is expected to be used to help debug when some fatal error
     23  * happens.
     24  *
     25  * IMPORTANT NOTE: since the (major) intended use case of this module is
     26  * dumping a back trace on a fatal error, normally followed by self termination,
     27  * functions defined in this module generally doesn't employ assertion checks
     28  * (if it did, a program bug could cause infinite recursive calls to a
     29  * backtrace function).
     30  */
     31 
     32 #pragma once
     33 
     34 /***
     35  ***	Imports
     36  ***/
     37 #include <isc/types.h>
     38 
     39 /*
     40  * The maximum number of stack frames to dump on assertion failure.
     41  */
     42 #ifndef ISC_BACKTRACE_MAXFRAME
     43 #define ISC_BACKTRACE_MAXFRAME 128
     44 #endif /* ifndef ISC_BACKTRACE_MAXFRAME */
     45 
     46 /***
     47  *** Functions
     48  ***/
     49 
     50 ISC_LANG_BEGINDECLS
     51 int
     52 isc_backtrace(void **addrs, int maxaddrs);
     53 /*%<
     54  * Get a back trace of the running process above this function itself.  On
     55  * success, addrs[i] will store the address of the call point of the i-th
     56  * stack frame (addrs[0] is the caller of this function).  *nframes will store
     57  * the total number of frames.
     58  *
     59  * Requires (note that these are not ensured by assertion checks, see above):
     60  *
     61  *\li	'addrs' is a valid array containing at least 'maxaddrs' void * entries.
     62  *
     63  *\li	'nframes' must be non NULL.
     64  *
     65  * Returns:
     66  *
     67  *\li	#ISC_R_SUCCESS
     68  *\li	#ISC_R_FAILURE
     69  *\li	#ISC_R_NOTFOUND
     70  *\li	#ISC_R_NOTIMPLEMENTED
     71  */
     72 
     73 char **
     74 isc_backtrace_symbols(void *const *buffer, int size);
     75 /*
     76  * isc_backtrace_symbols() attempts to transform a call stack obtained by
     77  * backtrace() into an array of human-readable strings using dladdr().  The
     78  * array of strings returned has size elements.  It is allocated using
     79  * malloc() and should be released using free().  There is no need to free
     80  * the individual strings in the array.
     81  *
     82  * Notes:
     83  *
     84  *\li	On systems with backtrace_symbols(), it's just a thin wrapper
     85  *\li	Otherwise, it returns NULL
     86  *\li	See platform NOTES for backtrace_symbols
     87  *
     88  * Returns:
     89  *
     90  *\li	On success, backtrace_symbols() returns a pointer to the array
     91  *\li	On error, NULL is returned.
     92  */
     93 
     94 void
     95 isc_backtrace_symbols_fd(void *const *buffer, int size, int fd);
     96 /*
     97  * isc_backtrace_symbols_fd() performs the same operation as
     98  * isc_backtrace_symbols(), but the resulting strings are immediately written to
     99  * the file descriptor fd, and are not returned.  isc_backtrace_symbols_fd()
    100  * does not call malloc(3), and so can be employed in situations where the
    101  * latter function might fail.
    102  *
    103  * Notes:
    104  *
    105  *\li	See isc_backtrace_symbols() notes
    106  *\li	See platform NOTES for backtrace_symbols_fd for caveats
    107  */
    108 
    109 void
    110 isc_backtrace_log(isc_log_t *lctx, isc_logcategory_t *category,
    111 		  isc_logmodule_t *module, int level);
    112 /*
    113  * Write a backtrace to the log.
    114  */
    115 
    116 ISC_LANG_ENDDECLS
    117