### Complete libstapsdt Usage Example Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html This example demonstrates the full lifecycle of using libstapsdt, from provider and probe creation to loading, firing, unloading, and destruction. ```c #include #include #include int main() { int i=1; SDTProvider_t *provider; SDTProbe_t *probe; provider = providerInit("myLittleProvider"); probe = providerAddProbe(provider, "myLittleProbe", 1, uint64); if(providerLoad(provider) == -1) { printf("Something went wrong...\n"); return -1; } while(i) { printf("Firing probe...\n"); if(probeIsEnabled(probe)) { probeFire(probe, "I'm a runner!"); printf("Probe fired!\n"); i = 0; } sleep(1); } providerUnload(provider); providerDestroy(provider); return 0; } ``` -------------------------------- ### Run the libstapsdt Demo Program Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html Execute the libstapsdt demo program with specified provider and probe names. This helps in testing the installed library. ```bash ./demo PROVIDER_NAME PROBE_NAME ``` -------------------------------- ### Build and Install libstapsdt from Source Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html Compile and install the libstapsdt library from its source code. This process includes building the library and updating the dynamic linker cache. ```bash make sudo make install sudo ldconfig ``` -------------------------------- ### Install libstapsdt on Ubuntu via PPA Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html Add the Sthima's Open Source Software PPA and install the libstapsdt packages. This is the recommended method for Ubuntu users. ```bash sudo add-apt-repository ppa:sthima/oss sudo apt-get update sudo apt-get install libstapsdt0 libstapsdt-dev ``` -------------------------------- ### Install libstapsdt Dependencies on Ubuntu Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html Install the necessary libelf dependency for building libstapsdt from source on Ubuntu. This is a prerequisite for the build process. ```bash sudo apt install libelf1 libelf-dev ``` -------------------------------- ### Systemtap SDT Probe Registration Example Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/internals.html This C code demonstrates how to register a Systemtap SDT probe named 'Probe' to a provider named 'Provider' using the DTRACE_PROBE macro. ```c #include int main() { DTRACE_PROBE(Provider, Probe); return 0; } ``` -------------------------------- ### Build the libstapsdt Demo Program Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html Compile the provided demo program for libstapsdt. The executable will be generated in the current directory. ```bash make demo # Executable will be available at ./demo ``` -------------------------------- ### providerInit Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html Initializes a new SDTProvider_t with a given name. It creates the provider with all attributes correctly initialized. Returns a pointer to the new provider or NULL if an error occurs. ```APIDOC ## providerInit ### Description Initializes a new SDTProvider_t with a given name. It creates the provider with all attributes correctly initialized. Returns a pointer to the new provider or NULL if an error occurs. ### Parameters #### Path Parameters - **name** (string) - The name of this provider ### Return Type SDTProvider_t* ### Returns A pointer to the new provider or NULL if an error occurs. ``` -------------------------------- ### Provider and Probe Initialization Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html Initializes a libstapsdt provider and registers a probe with specified arguments and types. Ensure the provider name and probe details are unique and appropriate for your use case. ```c SDTProvider_t *provider; SDTProbe_t *probe; provider = providerInit("myLittleProvider"); probe = providerAddProbe(provider, "myLittleProbe", 1, uint64); ``` -------------------------------- ### Trace libstapsdt Demo with bcc trace Source: https://libstapsdt.readthedocs.io/en/latest/getting-started/getting-started.html Use the bcc trace tool to monitor probes from the libstapsdt demo program. This requires the process ID of the running demo. ```bash sudo /usr/share/bcc/tools/trace -p $(pgrep demo) 'u::PROBE_NAME' ``` -------------------------------- ### Loading the Provider Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html Loads the libstapsdt provider, making its registered probes available for tracing. Error handling is crucial here; a return value of -1 indicates a failure. ```c if(providerLoad(provider) == -1) { printf("Something went wrong...\n"); return -1; } ``` -------------------------------- ### Elf Section and Note for Systemtap SDT Probes Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/internals.html This output shows the Elf notes generated for Systemtap SDT probes, including provider name, probe name, location, base address, semaphore, and arguments. ```text Displaying notes found at file offset 0x00001064 with length 0x0000003c: Owner Data size Description stapsdt 0x00000028 NT_STAPSDT (SystemTap probe descriptors) Provider: Provider Name: Probe Location: 0x00000000004004da, Base: 0x0000000000400574, Semaphore: 0x0000000000000000 Arguments: ``` -------------------------------- ### providerLoad Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html Loads a provider, making all its registered probes available for tracing. Returns 0 on success, or a non-zero number on error. After loading, no new probes can be added, and the provider cannot be loaded again. ```APIDOC ## providerLoad ### Description Loads a provider, making all its registered probes available for tracing. Returns 0 on success, or a non-zero number on error. After loading, no new probes can be added, and the provider cannot be loaded again. ### Parameters #### Path Parameters - **provider** (SDTProvider_t*) - The provider to be loaded ### Return Type int ### Returns A status code (0 means success, other numbers indicate error). ``` -------------------------------- ### probeFire Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html Fires a probe if it is available for tracing (i.e., if providerLoad() was called previously). Accepts any number of arguments that match the probe's expected arguments. ```APIDOC ## probeFire ### Description Fires a probe if it is available for tracing (i.e., if providerLoad() was called previously). Accepts any number of arguments that match the probe's expected arguments. ### Parameters #### Path Parameters - **probe** (SDTProbe_t*) - The probe to be fired - **...** (any) - Any number of arguments (must match the expected number of arguments for this probe) ``` -------------------------------- ### providerAddProbe Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html Adds a new SDTProbe_t to an existing SDTProvider_t. The probe is created with a given name, argument count, and argument types. Returns a pointer to the created probe or NULL if an error occurs. ```APIDOC ## providerAddProbe ### Description Adds a new SDTProbe_t to an existing SDTProvider_t. The probe is created with a given name, argument count, and argument types. Returns a pointer to the created probe or NULL if an error occurs. ### Parameters #### Path Parameters - **provider** (SDTProvider_t*) - The provider where this probe will be created - **name** (string) - The name of this probe - **argCount** (int) - The number of arguments accepted by this probe - **...** (SDTArgTypes_t) - Any number of arguments (number of arguments must match argCount) ### Return Type SDTProbe_t* ### Returns A pointer to the new provider or NULL if an error occurs. ``` -------------------------------- ### providerDestroy Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html Frees an SDTProvider_t and all its registered SDTProbe_t from memory. ```APIDOC ## providerDestroy ### Description Frees an SDTProvider_t and all its registered SDTProbe_t from memory. ### Parameters #### Path Parameters - **provider** (SDTProvider_t*) - The provider to be freed from memory, along with its probes ``` -------------------------------- ### providerUnload Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html Unloads a provider, making its probes unavailable for tracing. Returns 0 on success, or a non-zero number on error. After unloading, new probes can be added to the provider again. ```APIDOC ## providerUnload ### Description Unloads a provider, making its probes unavailable for tracing. Returns 0 on success, or a non-zero number on error. After unloading, new probes can be added to the provider again. ### Parameters #### Path Parameters - **provider** (SDTProvider_t*) - The provider to be unloaded ### Return Type int ### Returns A status code (0 means success, other numbers indicate error). ``` -------------------------------- ### Unloading and Destroying Provider Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html Unloads the libstapsdt provider and destroys it to free allocated resources. It is essential to call `providerUnload()` before `providerDestroy()` to prevent memory leaks and segmentation faults. ```c providerUnload(provider); providerDestroy(provider); ``` -------------------------------- ### Conditional Probe Firing Source: https://libstapsdt.readthedocs.io/en/latest/how-it-works/how-to-use.html Checks if a probe is enabled using `probeIsEnabled()` before firing it with `probeFire()`. This ensures probes are only activated when tracing is active, preventing unnecessary operations. ```c while(i) { printf("Firing probe...\n"); if(probeIsEnabled(probe)) { probeFire(probe, "I'm a runner!"); printf("Probe fired!\n"); i = 0; } sleep(1); } ``` -------------------------------- ### probeIsEnabled Source: https://libstapsdt.readthedocs.io/en/latest/api/functions.html Checks if a probe is currently being traced. Returns 1 if the probe is enabled, and 0 otherwise. ```APIDOC ## probeIsEnabled ### Description Checks if a probe is currently being traced. Returns 1 if the probe is enabled, and 0 otherwise. ### Parameters #### Path Parameters - **probe** (SDTProbe_t*) - The probe to be checked ### Return Type int ### Returns 1 if probe is enabled, 0 otherwise. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.