follow-up to 584e2a1 - configurable signal, refactoring, add tests

Author: d99kris

CMakeLists.txt

@@ -23,12 +23,10 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
 # Library
-add_library(heapusage SHARED src/humain.cpp src/hulog.cpp src/humalloc.cpp src/huapi.cpp)
-set_target_properties(heapusage PROPERTIES PUBLIC_HEADER "src/huapi.h")
+add_library(heapusage SHARED src/humain.cpp src/hulog.cpp src/humalloc.cpp)
+set_target_properties(heapusage PROPERTIES PUBLIC_HEADER "src/heapusage.h")
 target_compile_features(heapusage PRIVATE cxx_variadic_templates)
-install(TARGETS heapusage
-    LIBRARY DESTINATION lib
-    PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(TARGETS heapusage LIBRARY DESTINATION lib PUBLIC_HEADER DESTINATION include)
 target_link_libraries(heapusage pthread dl)
 
 # Dependency backward-cpp providing more detailed stacktraces on Linux, when
@@ -49,17 +47,23 @@ install(FILES src/heapusage.1 DESTINATION share/man/man1)
 # Tests
 enable_testing()
 
+include_directories("src")
 add_executable(ex001 tests/ex001.c)
 add_executable(ex002 tests/ex002.c)
 add_executable(ex003 tests/ex003.cpp)
 add_executable(ex004 tests/ex004.cpp)
 add_executable(ex005 tests/ex005.cpp)
+add_executable(ex006 tests/ex006.cpp)
+add_executable(ex007 tests/ex007.cpp src/heapusage.h)
 
 target_compile_options(ex001 PRIVATE -O0)
 target_compile_options(ex002 PRIVATE -O0)
 target_compile_options(ex003 PRIVATE -O0)
 target_compile_options(ex004 PRIVATE -O0)
 target_compile_options(ex005 PRIVATE -O0)
+target_compile_options(ex006 PRIVATE -O0)
+target_compile_options(ex007 PRIVATE -O0)
+target_link_libraries(ex007 heapusage)
 
 configure_file(tests/test001 ${CMAKE_CURRENT_BINARY_DIR}/test001 COPYONLY)
 add_test(test001 "${PROJECT_BINARY_DIR}/test001")
@@ -75,3 +79,9 @@ add_test(test004 "${PROJECT_BINARY_DIR}/test004")
 
 configure_file(tests/test005 ${CMAKE_CURRENT_BINARY_DIR}/test005 COPYONLY)
 add_test(test005 "${PROJECT_BINARY_DIR}/test005")
+
+configure_file(tests/test006 ${CMAKE_CURRENT_BINARY_DIR}/test006 COPYONLY)
+add_test(test006 "${PROJECT_BINARY_DIR}/test006")
+
+configure_file(tests/test007 ${CMAKE_CURRENT_BINARY_DIR}/test007 COPYONLY)
+add_test(test007 "${PROJECT_BINARY_DIR}/test007")

README.md

@@ -101,6 +101,9 @@ Options:
     -o <path>
            write output to specified file path, instead of stderr
 
+    -s <SIG>
+           enable on-demand logging when signalled SIG signal
+
     -t <tools>
            analysis tools to use (default "leak")
 
@@ -136,20 +139,6 @@ Examples:
     heapusage -t all -m 0 ./ex002
            analyze heap allocations of any size with all tools.
 
-Programs being ran with Heapusage can themselves also request reports from
-Heapusage, while the program is running, by using the `hu_report()` public API
-function. For doing so, they must include the `huapi.h` public header file, link
-with the Heapusage shared library itself and call `hu_report()` when wanted.
-Still, this only works if the program is running through the `heapusage` tool.
-
-Alternatively, on Linux, sending a `SIGUSR1` signal to the program being run
-through Heapusage will also produce a Heapusage report on demand.
-
-For both `hu_report()` and `SIGUSR1`, it should be noted that the report will
-reflect the state when they are used, which can e.g. report non-freed memory
-that might be still released before the program exits and, therefore, not
-necessarily constitute a memory leak.
-
 Output Format
 =============
 Example output:
@@ -181,6 +170,21 @@ Source code filename and line numbers are only supported on Linux, when package
 binutils-dev is available. On macOS one can use atos to determine source code
 details.
 
+Advanced Usage
+==============
+On-demand report can be requested by utilizing the `-s` flag and specifying a
+signal, and the sending the signal to the process. Example:
+
+    ./build/heapusage -s SIGUSR1 -t all -m 0 -o hu.txt nano
+    kill -s SIGUSR1 $(pidof nano)
+
+Programs can also link libheapusage and call `hu_report()` for an on-demand
+report, see `tests/ex007.cpp` for an example.
+
+Note that on-demand reporting will reflect the state when they are used, and
+will thus report memory currently in use that might still be released before
+the program exits, and therefore not necessarily constitute a memory leak.
+
 Technical Details
 =================
 Heapusage intercepts calls to malloc/free/calloc/realloc and logs each memory

src/heapusage

@@ -10,7 +10,7 @@ showusage()
   echo "Heapusage is a light-weight tool for finding heap memory errors in"
   echo "applications."
   echo ""
-  echo "Usage: heapusage [-d] [-m minsize] [-n] [-o path] [-t tools] PROG [ARGS..]"
+  echo "Usage: heapusage [-d] [-m minsize] [-n] [-o path] [-s SIG] [-t tools] PROG [ARGS..]"
   echo "   or: heapusage --help"
   echo "   or: heapusage --version"
   echo ""
@@ -19,6 +19,7 @@ showusage()
   echo "   -m <minsize>    min alloc size to enable analysis for (default 0)"
   echo "   -n              no symbol lookup (faster)"
   echo "   -o <path>       write output to specified file path, instead of stderr"
+  echo "   -s <SIG>        enable on-demand logging when signalled SIG signal"
   echo "   -t <tools>      analysis tools to use (default \"leak\")"
   echo "   PROG            program to run and analyze"
   echo "   [ARGS]          optional arguments to the program"
@@ -46,7 +47,7 @@ showusage()
 
 showversion()
 {
-  echo "heapusage v2.09"
+  echo "heapusage v2.10"
   echo ""
   echo "Copyright (C) 2017-2024 Kristofer Berggren"
   echo ""
@@ -72,8 +73,9 @@ DEBUG="0"
 MINSIZE="0"
 NOSYMS="0"
 OUTFILE=""
+SIGNO=""
 TOOLS="leak"
-while getopts "?dfm:no:t:" OPT; do
+while getopts "?dfm:no:s:t:" OPT; do
   case "${OPT}" in
   \?)
     showusage
@@ -91,6 +93,18 @@ while getopts "?dfm:no:t:" OPT; do
   o)
     OUTFILE="${OPTARG}"
     ;;
+  s)
+    if ! [[ "${OPTARG}" =~ ^[0-9]+$ ]]; then
+      # Not a number, try signal name
+      SIGNO="$(kill -l ${OPTARG} 2> /dev/null)"
+      if [[ "${SIGNO}" == "" ]]; then
+        echo "error: unknown signal name ${OPTARG}"
+        exit 1
+      fi
+    else
+      SIGNO="${OPTARG}"
+    fi
+    ;;
   t)
     TOOLS="${OPTARG}"
     ;;
@@ -201,6 +215,7 @@ while [ "${LIBPATHS[CNT]}" != "" ]; do
       HU_FILE="${TMPLOG}${OUTFILE}"         \
       HU_MINSIZE="${MINSIZE}"               \
       HU_NOSYMS="${NOSYMS}"                 \
+      HU_SIGNO="${SIGNO}"                   \
       LD_PRELOAD="${LIBPATH}"               \
       DYLD_INSERT_LIBRARIES="${LIBPATH}"    \
       DYLD_FORCE_FLAT_NAMESPACE=1           \
@@ -214,6 +229,7 @@ while [ "${LIBPATHS[CNT]}" != "" ]; do
       echo "env HU_FILE=\"${TMPLOG}${OUTFILE}\""        >> "${LLDBCMDPATH}"
       echo "env HU_MINSIZE=\"${MINSIZE}\""              >> "${LLDBCMDPATH}"
       echo "env HU_NOSYMS=\"${NOSYMS}\""                >> "${LLDBCMDPATH}"
+      echo "env HU_SIGNO=\"${SIGNO}\""                  >> "${LLDBCMDPATH}"
       echo "env LD_PRELOAD=\"${LIBPATH}\""              >> "${LLDBCMDPATH}"
       echo "env DYLD_INSERT_LIBRARIES=\"${LIBPATH}\""   >> "${LLDBCMDPATH}"
       echo "env DYLD_FORCE_FLAT_NAMESPACE=1"            >> "${LLDBCMDPATH}"

src/heapusage.1

@@ -1,10 +1,10 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
-.TH HEAPUSAGE "1" "June 2024" "heapusage v2.09" "User Commands"
+.TH HEAPUSAGE "1" "June 2024" "heapusage v2.10" "User Commands"
 .SH NAME
 heapusage \- find memory leaks in applications
 .SH SYNOPSIS
 .B heapusage
-[\fI\,-d\/\fR] [\fI\,-m minsize\/\fR] [\fI\,-n\/\fR] [\fI\,-o path\/\fR] [\fI\,-t tools\/\fR] \fI\,PROG \/\fR[\fI\,ARGS\/\fR..]
+[\fI\,-d\/\fR] [\fI\,-m minsize\/\fR] [\fI\,-n\/\fR] [\fI\,-o path\/\fR] [\fI\,-s SIG\/\fR] [\fI\,-t tools\/\fR] \fI\,PROG \/\fR[\fI\,ARGS\/\fR..]
 .br
 .B heapusage
 \fI\,--help\/\fR
@@ -28,6 +28,9 @@ no symbol lookup (faster)
 \fB\-o\fR <path>
 write output to specified file path, instead of stderr
 .TP
+\fB\-s\fR <SIG>
+enable on\-demand logging when signalled SIG signal
+.TP
 \fB\-t\fR <tools>
 analysis tools to use (default "leak")
 .TP

src/huapi.h src/heapusage.h

@@ -1,16 +1,14 @@
 /*
- * huapi.h
+ * heapusage.h
  *
- * Copyright (C) 2021 Kristofer Berggren
+ * Copyright (C) 2024 Kristofer Berggren
  * All rights reserved.
  *
  * heapusage is distributed under the BSD 3-Clause license, see LICENSE for details.
  *
  */
 
-#ifndef _HUAPI_H_
-#define _HUAPI_H_
-
+#pragma once
 
 /* ----------- Global Function Prototypes ------------------------ */
 
@@ -23,5 +21,3 @@ void hu_report(void);
 #ifdef __cplusplus
 }
 #endif
-
-#endif /* _HUAPI_H_ */

src/huapi.cpp

@@ -1,7 +1,7 @@
 /*
  * hulog.cpp
  *
- * Copyright (C) 2017-2022 Kristofer Berggren
+ * Copyright (C) 2017-2024 Kristofer Berggren
  * All rights reserved.
  * 
  * heapusage is distributed under the BSD 3-Clause license, see LICENSE for details.
@@ -20,7 +20,6 @@
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
-#include <stdarg.h>
 
 #include <map>
 #include <set>
@@ -386,31 +385,7 @@ void hu_sig_handler(int sig, siginfo_t* si, void* /*ucontext*/)
   exit(EXIT_FAILURE);
 }
 
-void log_message(const char *format, ...)
-{
-  va_list args;
-
-  FILE *f = NULL;
-  if (hu_log_file)
-  {
-    f = fopen(hu_log_file, "a");
-  }
-
-  if (!f)
-  {
-    return;
-  }
-
-  fprintf(f, "==%d== MESSAGE: ", pid);
-
-  va_start(args, format);
-  vfprintf(f, format, args);
-  va_end(args);
-
-  fclose(f);
-}
-
-void log_summary()
+void log_summary(bool ondemand)
 {
   FILE *f = NULL;
   if (hu_log_file)
@@ -455,6 +430,12 @@ void log_summary()
       allocations_by_size.insert(it->second);
   }
 
+  /* Indicate in case an on-demand report */
+  if (ondemand)
+  {
+    fprintf(f, "==%d== ON DEMAND REPORT\n", pid);
+  }
+
   /* Output heap summary */
   fprintf(f, "==%d== HEAP SUMMARY:\n", pid);
   fprintf(f, "==%d==     in use at exit: %llu bytes in %llu blocks\n",
@@ -490,17 +471,6 @@ void log_summary()
   fclose(f);
 }
 
-void log_summary_safe()
-{
-  hu_set_bypass(true);
-  log_enable(0);
-
-  log_summary();
-
-  log_enable(1);
-  hu_set_bypass(false);
-}
-
 void hu_log_remove_freed_allocation(void* ptr)
 {
   if (!hu_log_free)

src/hulog.cpp

@@ -1,13 +1,15 @@
 /*
  * hulog.h
  *
- * Copyright (C) 2017-2021 Kristofer Berggren
+ * Copyright (C) 2017-2024 Kristofer Berggren
  * All rights reserved.
  * 
  * heapusage is distributed under the BSD 3-Clause license, see LICENSE for details.
  *
  */
 
+#pragma once
+
 /* ----------- Includes ------------------------------------------ */
 #include <signal.h>
 
@@ -24,7 +26,5 @@ void log_enable(int flag);
 void log_event(int event, void* ptr, size_t size);
 void log_invalid_access(void* ptr);
 void hu_sig_handler(int sig, siginfo_t* si, void* /*ucontext*/);
-void log_message(const char *format, ...);
-void log_summary();
-void log_summary_safe();
+void log_summary(bool ondemand);
 void hu_log_remove_freed_allocation(void* ptr);