{"id":31927030,"url":"https://github.com/throwtheswitch/cexception","last_synced_at":"2025-10-14T01:56:29.368Z","repository":{"id":2316651,"uuid":"3276873","full_name":"ThrowTheSwitch/CException","owner":"ThrowTheSwitch","description":"Lightweight exception implementation for C","archived":false,"fork":false,"pushed_at":"2025-02-17T14:30:07.000Z","size":581,"stargazers_count":348,"open_issues_count":2,"forks_count":69,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-10-03T06:37:22.713Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://throwtheswitch.org","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThrowTheSwitch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"license.txt","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ThrowTheSwitch"}},"created_at":"2012-01-26T19:53:33.000Z","updated_at":"2025-09-30T02:53:39.000Z","dependencies_parsed_at":"2024-03-17T04:31:42.940Z","dependency_job_id":"ecb1811f-2ab0-43a6-80b8-453ec654fdff","html_url":"https://github.com/ThrowTheSwitch/CException","commit_stats":{"total_commits":71,"total_committers":17,"mean_commits":4.176470588235294,"dds":0.647887323943662,"last_synced_commit":"a2581509b81c8d762c21b69d024a053c7cfce8cb"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ThrowTheSwitch/CException","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThrowTheSwitch%2FCException","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThrowTheSwitch%2FCException/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThrowTheSwitch%2FCException/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThrowTheSwitch%2FCException/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThrowTheSwitch","download_url":"https://codeload.github.com/ThrowTheSwitch/CException/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThrowTheSwitch%2FCException/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017469,"owners_count":26086090,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-10-14T01:56:08.521Z","updated_at":"2025-10-14T01:56:29.363Z","avatar_url":"https://github.com/ThrowTheSwitch.png","language":"C","funding_links":["https://github.com/sponsors/ThrowTheSwitch"],"categories":[],"sub_categories":[],"readme":"CException ![CI](https://github.com/ThrowTheSwitch/CException/workflows/CI/badge.svg)\n==========\n\n_This Documentation Is Released Under a Creative Commons 3.0 Attribution Share-Alike License_\n\nCException is simple exception handling in C. It is significantly faster than full-blown C++ exception handling \nbut loses some flexibility. It is portable to any platform supporting `setjmp`/`longjmp`.\n\nGetting Started\n================\n\nThe simplest way to get started is to just grab the code and pull it into your project:\n\n```\ngit clone https://github.com/throwtheswitch/cexception.git\n```\n\nIf you want to contribute to this project, you'll also need to have Ruby and Ceedling installed to run the unit tests.\n\nUsage\n=====\n\n### So what's it good for?\n\nMostly error handling. Passing errors down a long chain of function calls gets ugly. Sometimes really ugly. \nSo what if you could just specify certain places where you want to handle errors, and all your errors were \ntransferred there? Let's try a lame example:\n\nCException uses C standard library functions setjmp and longjmp to operate. As long as the target system \nhas these two functions defined, this library should be useable with very little configuration. It even \nsupports environments where multiple program flows are in use, such as real-time operating systems... \nwe started this project for use in embedded systems... but it obviously can be used for larger systems too.\n\n### Error Handling with CException:\n\n```\nvoid functionC(void) {\n  //do some stuff\n  if (there_was_a_problem)\n    Throw(ERR_BAD_BREATH);\n  //this stuff never gets called because of error\n}\n```\n\nThere are about a gajillion exception frameworks using a similar setjmp/longjmp method out there... and there \nwill probably be more in the future. Unfortunately, when we started our last embedded project, all those that \nexisted either (a) did not support multiple tasks (therefore multiple stacks) or (b) were way more complex \nthan we really wanted. CException was born.\n\nWhy?\n====\n\n### It's ANSI C\n\n...and it beats passing error codes around.\n\n### You want something simple...\n\nCException throws a single id. You can define those ID's to be whatever you like. \nYou might even choose which type that number is for your project. But that's as far as it goes. We weren't interested \nin passing objects or structs or strings... just simple error codes. Fast. Easy to Use. Easy to Understand.\n\n### Performance...\n\nCException can be configured for single tasking or multitasking. In single tasking, there is \nvery little overhead past the setjmp/longjmp calls (which are already fast). In multitasking, your only additional \noverhead is the time it takes you to determine a unique task id (0 to num_tasks).\n\nHow?\n====\n\nCode that is to be protected are wrapped in `Try { }` blocks. The code inside the Try block is _protected_, \nmeaning that if any Throws occur, program control is directly transferred to the start of the Catch block. \nThe Catch block immediately follows the Try block. It's ignored if no errors have occurred.\n\nA numerical exception ID is included with Throw, and is passed into the Catch block. This allows you to handle \nerrors differently or to report which error has occurred... or maybe it just makes debugging easier so you \nknow where the problem was Thrown.\n\nThrows can occur from anywhere inside the Try block, directly in the function you're testing or even within \nfunction calls (nested as deeply as you like). There can be as many Throws as you like, just remember that \nexecution of the guts of your Try block ends as soon as the first Throw is triggered. Once you throw, you're \ntransferred to the Catch block. A silly example:\n\n```\nvoid SillyExampleWhichPrintsZeroThroughFive(void) {\n  volatile CEXCEPTION_T e;\n  int i;\n  while (i = 0; i \u003c 6; i++) {\n    Try {\n      Throw(i);\n      //This spot is never reached\n    } \n    Catch(e) {\n      printf(“%i “, e);\n    }\n  }\n}\n```\n\nLimitations\n===========\n\nThis library was made to be as fast as possible, and provide basic exception handling. It is not a full-blown \nexception library like C++. Because of this, there are a few limitations that should be observed in order to \nsuccessfully utilize this library:\n\n### Return \u0026 Goto\n\nDo not directly `return` from within a `Try` block, nor `goto` into or out of a `Try` block.\nThe `Try` macro allocates some local memory and alters a global pointer. These are cleaned up at the \ntop of the `Catch` macro. Gotos and returns would bypass some of these steps, resulting in memory leaks \nor unpredictable behavior.\n\n### Local Variables\n\nIf (a) you change local (stack) variables within your `Try` block, and (b) wish to make use of the updated \nvalues after an exception is thrown, those variables should be made `volatile`.\n\nNote that this is ONLY for locals and ONLY when you need access to them after a `Throw`.\n\nCompilers optimize (and thank goodness they do). There is no way to guarantee that the actual memory \nlocation was updated and not just a register unless the variable is marked volatile.\n\n### Memory Management\n\nMemory which is `malloc`'d within a `Try` block is not automatically released when an error is thrown. This \nwill sometimes be desirable, and other times may not. It will be the responsibility of the code you put in \nthe `Catch` block to perform this kind of cleanup.\n\nThere's just no easy way to track `malloc`'d memory, etc., without replacing or wrapping `malloc` \ncalls or something like that. This is a lightweight framework, so these options were not desirable.\n\nCException API\n==============\n\n### `Try { ... }`\n\n`Try` is a macro which starts a protected block. It MUST be followed by a pair of braces or a single \nprotected line (similar to an 'if'), enclosing the data that is to be protected. It MUST be followed by \na `Catch` block (don't worry, you'll get compiler errors to let you know if you mess any of that up).\n\nThe `Try` block is your protected block. It contains your main program flow, where you can ignore errors \n(other than a quick `Throw` call). You may nest multiple `Try` blocks if you want to handle errors at\nmultiple levels, and you can even rethrow an error from within a nested `Catch`.\n\n### `Catch(e) { }`\n\n`Catch` is a macro which ends the `Try` block and starts the error handling block. The `Catch` block \nis executed if and only if an exception was thrown while within the `Try` block. This error was thrown \nby a `Throw` call somewhere within `Try` (or within a function called within `Try`, or a function called \nby a function called within `Try`... you get the idea.).\n\n`Catch` receives a single id of type `CEXCEPTION_T` which you can ignore or use to handle the error in \nsome way. You may throw errors from within Catches, but they will be caught by a `Try` wrapping the `Catch`, \nnot the one immediately preceeding.\n\n### `Throw(e)`\n\n`Throw` is the method used to throw an error. `Throw`s should only occur from within a protected \n(`Try`...`Catch`) block, though it may easily be nested many function calls deep without an impact \non performance or functionality. `Throw` takes a single argument, which is an exception id which will be \n passed to `Catch` as the reason for the error. If you wish to _re-throw_ an error, this can be done by\ncalling `Throw(e)` with the error code you just caught. It _IS_ valid to throw from a `Catch` block.\n\n### `ExitTry()`\n\n`ExitTry` is a method used to immediately exit your current Try block but NOT treat this as an error. Don't \nrun the Catch. Just start executing from after the Catch as if nothing had happened.\n\nConfiguration\n=============\n\nCException is a mostly portable library. It has one universal dependency, plus some macros which are required if \nworking in a multi-tasking environment.\n\nThe standard C library setjmp must be available. Since this is part of the standard library, it's all good.\n\nIf working in a multitasking environment, you need a stack frame for each task. Therefore, you must define \nmethods for obtaining an index into an array of frames and to get the overall number of id's are required. If \nthe OS supports a method to retrieve task ID's, and those tasks are number 0, 1, 2... you are in an ideal \nsituation. Otherwise, a more creative mapping function may be required. Note that this function is likely to \nbe called twice for each protected block and once during a throw. This is the only added overhead in the system.\n\nYou have options for configuring the library, if the defaults aren't good enough for you. You can add defines \nat the command prompt directly. You can always include a configuration file before including `CException.h`. \nYou can make sure `CEXCEPTION_USE_CONFIG_FILE` is defined, which will force make CException look for \n`CExceptionConfig.h`, where you can define whatever you like. However you do it, you can override any or \nall of the following:\n\n### `CEXCEPTION_T`\n\nSet this to the type you want your exception id's to be. Defaults to an 'unsigned int'.\n\n### `CEXCEPTION_NONE`\n\nSet this to a number which will never be an exception id in your system. Defaults to `0x5a5a5a5a`.\n\n### `CEXCEPTION_GET_ID`\n\nIf in a multi-tasking environment, this should be set to be a call to the function described in #2 above. \nIt defaults to just return 0 all the time (good for single tasking environments, not so good otherwise).\n\n### `CEXCEPTION_NUM_ID`\n\nIf in a multi-tasking environment, this should be set to the number of ID's required (usually the number \nof tasks in the system). Defaults to 1 (good for single tasking environments or systems where you will only \nuse this from one task).\n\n### `CEXCEPTION_NO_CATCH_HANDLER (id)`\n\nThis macro can be optionally specified. It allows you to specify code to be called when a Throw is made \noutside of Try...Catch protection. Consider this the emergency fallback plan for when something has gone \nterribly wrong.\n\n### And More!\n\nYou may also want to include any header files which will commonly be needed by the rest of your application \nwhere it uses exception handling here. For example, OS header files or exception codes would be useful.\n\nFinally, there are some hook macros which you can implement to inject your own target-specific code in \nparticular places. It is a rare instance where you will need these, but they are here if you need them:\n\n* `CEXCEPTION_HOOK_START_TRY` - called immediately before the Try block\n* `CEXCEPTION_HOOK_HAPPY_TRY` - called immediately after the Try block if no exception was thrown\n* `CEXCEPTION_HOOK_AFTER_TRY` - called immediately after the Try block OR before an exception is caught\n* `CEXCEPTION_HOOK_START_CATCH` - called immediately before the catch\n\nTesting\n=======\n\nIf you want to validate that CException works with your tools or that it works with your custom \nconfiguration, you may want to run the included test suite. This is the test suite (along with real \nprojects we've used it on) that we use to make sure that things actually work the way we claim.\nThe test suite makes use of Ceedling, which uses the Unity Test Framework. It will require a native C compiler. \nThe example makefile and rakefile both use gcc. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrowtheswitch%2Fcexception","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthrowtheswitch%2Fcexception","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrowtheswitch%2Fcexception/lists"}