{"id":21094455,"url":"https://github.com/d99kris/stackusage","last_synced_at":"2025-05-16T14:33:23.879Z","repository":{"id":28102996,"uuid":"31601301","full_name":"d99kris/stackusage","owner":"d99kris","description":"Measure stack usage in Linux and macOS applications","archived":false,"fork":false,"pushed_at":"2023-01-15T08:35:10.000Z","size":409,"stargazers_count":67,"open_issues_count":0,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-07-07T00:37:46.087Z","etag":null,"topics":["linux","macos","memory-analysis","stack","stack-overflow"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d99kris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-03T14:05:00.000Z","updated_at":"2024-06-19T02:30:49.000Z","dependencies_parsed_at":"2023-01-16T22:16:44.277Z","dependency_job_id":null,"html_url":"https://github.com/d99kris/stackusage","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fstackusage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fstackusage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fstackusage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d99kris%2Fstackusage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d99kris","download_url":"https://codeload.github.com/d99kris/stackusage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225433465,"owners_count":17473599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","macos","memory-analysis","stack","stack-overflow"],"created_at":"2024-11-19T22:17:33.928Z","updated_at":"2024-11-19T22:17:34.580Z","avatar_url":"https://github.com/d99kris.png","language":"C","readme":"Stackusage\n==========\n\n| **Linux** | **Mac** |\n|-----------|---------|\n| [![Linux](https://github.com/d99kris/stackusage/workflows/Linux/badge.svg)](https://github.com/d99kris/stackusage/actions?query=workflow%3ALinux) | [![macOS](https://github.com/d99kris/stackusage/workflows/macOS/badge.svg)](https://github.com/d99kris/stackusage/actions?query=workflow%3AmacOS) |\n\nStackusage measures stack usage in Linux and macOS applications (main thread\nand native pthread child threads). The measured stack utilization data can be\nused to adjust the stack size allocation to provide desired margin for child\nthreads. This is primarily useful for applications and libraries designed to\nwork in resource-constrained environments (such as embedded systems).\n\nExample Usage\n=============\n\n    $ stackusage ./ex001\n    stackusage log start ----------------------------------------------------\n      pid  id    tid  requested     actual     maxuse  max%    dur  funcP\n    23930   0  23930    8388608    8384512       4144     0      0  (nil)\n    23930   1  23931      16384      16384       9336    56      0  0x4009b0\n    23930   2  23932      20480      20480      13528    66      0  0x4009b0\n    23930   3  23933      24576      24576      16728    68      0  0x4009b0\n    23930   4  23934      32768      32768      24920    76      0  0x4009b0\n    23930   5  23935      49152      49152      41304    84      0  0x4009b0\n    stackusage log end ------------------------------------------------------\n\nSupported Platforms\n===================\nStackusage is primarily developed and tested on Linux, but basic\nfunctionality should work in macOS / OS X as well. Current version has been\ntested on:\n- macOS Monterey 12.1\n- Ubuntu 20.04 LTS\n\nLimitation: On macOS / OS X this tool relies on code injection using\nDYLD_INSERT_LIBRARIES, which generally does not work with third-party\napplications in a standard system. Using it on (your own) applications built\nfrom source should work fine though.\n\nInstallation\n============\nPre-requisites (Ubuntu):\n\n    sudo apt install git cmake build-essential\n\nDownload the source code:\n\n    git clone https://github.com/d99kris/stackusage \u0026\u0026 cd stackusage\n\nGenerate Makefile and build:\n\n    mkdir -p build \u0026\u0026 cd build \u0026\u0026 cmake .. \u0026\u0026 make -s\n\nOptionally install in system:\n\n    sudo make install\n\nUsage\n=====\n\nGeneral usage syntax:\n\n    stackusage [-d] [-o PATH] [-s SIG] PROG [ARGS..]\n\nOptions:\n\n    -d              debug mode, running program through debugger\n    -o \u003cPATH\u003e       write output to specified file path, instead of stderr\n    -s \u003cSIG\u003e        enable on-demand logging when signalled SIG signal\n    PROG            program to run and analyze\n    [ARGS..]        optional arguments to the program\n    --help          display this help and exit\n    --version       output version information and exit\n\nExample checking stack usage of test program 'ex001' with stackusage installed\non system:\n\n    stackusage ./ex001\n\nExample performing on-demand logging of program 'gedit'\n\n    stackusage -s SIGUSR1 gedit\n    kill -s SIGUSR1 `pidof gedit`\n\nOutput Format\n=============\nExample output:\n\n    stackusage log start ----------------------------------------------------\n      pid  id    tid  requested     actual     maxuse  max%    dur  funcP\n    23930   0  23930    8388608    8384512       4144     0      0  (nil)\n    23930   1  23931      16384      16384       9336    56      0  0x4009b0\n    23930   2  23932      20480      20480      13528    66      0  0x4009b0\n    23930   3  23933      24576      24576      16728    68      0  0x4009b0\n    23930   4  23934      32768      32768      24920    76      0  0x4009b0\n    23930   5  23935      49152      49152      41304    84      0  0x4009b0\n    stackusage log end ------------------------------------------------------\n\nDescription of columns:\n\n    pid         process id\n    id          id (0 = main thread, 1 = first child thread, etc..)\n    tid         thread id / tid (only supported on Linux, others show '0')\n    requested   requested stack size in bytes\n    actual      actual stack size in bytes (excl. any stack guard)\n    maxuse      maximum stack usage in bytes\n    max%        maximum use of requested stack size in percentage\n    dur         thread duration in seconds\n    funcP       (nil) for main, pointer to start_routine for child threads\n\nThe function that funcP points to can be determined for example using\naddr2line:\n\n    $ addr2line -f -e ./ex001 0x4009b0\n    thread_start\n    ./tests/ex001.c:81\n\nTechnical Details\n=================\nStackusage intercepts calls to pthread_create and fills the thread\nstack with a dummy data pattern. It also registers a callback routine to be\ncalled upon thread termination. In the callback routine the amount of remaining\ndummy pattern in the stack is checked, in order to determine the stack usage.\n\nInterception is only possible when stackusage is built for the same\narchitecture as the program being analyzed. Stackusage tries to determine if\nthere is a mismatch, if encountered it will output a warning like this:\n\n    warning: libstackusage.so architecture (ELF 64-bit) does not appear\n    to match \u003cPROG\u003e architecture (ELF 32-bit), analysis may fail.\n\nTo solve this, simply compile stackusage for the appropriate architecture, for\nexample by adding `-m32` to CMAKE_C_FLAGS in CMakeLists.txt, example:\n\n    set(CMAKE_C_FLAGS \"${CMAKE_C_FLAGS} -std=gnu99 -g -m32 \\\n\nLicense\n=======\nStackusage is distributed under the BSD 3-Clause license. See LICENSE file.\n\nKeywords\n========\nlinux, macos, os x, pthreads, stack usage, stack utilization, threads.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd99kris%2Fstackusage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd99kris%2Fstackusage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd99kris%2Fstackusage/lists"}