Qp0zDumpStack()--Dump Formatted Stack Trace Data
Syntax
#include <qp0ztrc.h> void Qp0zDumpStack(const char *label);
Service Program Name: QP0ZCPA
Default Public Authority: *USE
Threadsafe: Yes
The Qp0zDumpStack() function dumps a formatted representation of the call stack of the calling thread to the user trace. The formatted call stack is labeled with the text string specified by label. The formatted call stack shows the library, program, module, and procedure information associated with each frame on the call stack.
The formatted dump of the current call stack shows the oldest entries first, followed by newer entries.
The following example is a call stack dump if the Qp0zDumpStack() function is used to dump the stack of the current thread. The label Thread dumping my own stack was inserted by the application program using the label parameter.
The thread start routine in this example is threadfunc() in program or service program ATEST5 that resides in library QP0WTEST. The threadfunc() function (at statement 2) has called the function foo(). The function foo() (at statement 1), in turn has called bar(). The function bar() (at statement 1), has dumped the current call stack due to some application-specific error condition.
Thread dumping my own stack Library / Program Module Stmt Procedure QSYS / QLESPI QLECRTTH 7 : LE_Create_Thread2 QSYS / QP0WPTHR QP0WPTHR 974 : pthread_create_part2 QP0WTEST / ATEST5 ATEST5 2 : threadfunc QP0WTEST / ATEST5 ATEST5 1 : foo QP0WTEST / ATEST5 ATEST5 1 : bar QSYS / QP0ZCPA QP0ZUDBG 5 : Qp0zDumpStack QSYS / QP0ZSCPA QP0ZSCPA 199 : Qp0zSUDumpStack QSYS / QP0ZSCPA QP0ZSCPA 210 : Qp0zSUDumpTargetStack
An application should not use the tracing function in performance critical code. These functions are intended for debugging exception or error conditions. The user trace is a permanent user space object named QP0Z<jobnumber> in the QUSRSYS library. The user trace is created the first time any thread in a job writes trace output. See the Change User Trace (CHGUSRTRC), Dump User Trace (DMPUSRTRC) and Delete User Trace (DLTUSRTRC) CL commands for information about manipulating the user trace properties and objects.
Parameters
- label
- (Input) A pointer to a string that is used to label the stack dump.
Authorities
None.
Return Value
None.
Error Conditions
If Qp0zDumpStack() is not successful, the function returns immediately and no error is indicated.
Usage Notes
- No locks are held on the user trace between calls to the tracing functions.
The user trace can be deleted while in use. The next function that produces
trace output will create the user trace again.
- If another job on the system has the same job number as an existing user
trace, the existing trace data is cleared, and the trace data from the new job
replaces it.
- If the calling thread has more than 128 call stack entries,
Qp0zDumpStack() returns after dumping the first 128 entries of the
call stack.
- As the format of the user trace records can change, only the following CL
commands can be used to manipulate the user trace properties and objects:
- Change User Trace (CHGUSRTRC) can be used to change the characteristics of
the user trace.
- Dump User Trace (DMPUSRTRC) can be used to dump trace records to a file or
to standard output.
- Delete User Trace (DLTUSRTRC) can be used to delete the user trace objects.
- Change User Trace (CHGUSRTRC) can be used to change the characteristics of
the user trace.
Related Information
- Qp0zDump()--Dump Formatted Storage Trace Data
- Qp0zDumpTargetStack()--Dump Formatted Stack Trace
Data of the Target Thread
- Qp0zLprintf()--Print Formatted Job Log Data
- Qp0zUprintf()--Print Formatted User Trace Data
Example
The following example uses Qp0zDumpStack() and Qp0zUprintf() functions to produce trace output.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#define _MULTI_THREADED #include <pthread.h> #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <qp0ztrc.h> #define THREADDATAMAX 128 void foo(char *string); void bar(char *string); void *theThread(void *parm) { char *myData = parm; printf("Entered the %s thread\n", myData); foo(myData); free(myData); return NULL; } void foo(char *string) { bar(string); } void bar(char *string) { Qp0zUprintf("function bar(): Hit an error condition!\n"); Qp0zDumpStack(string); } int main(int argc, char **argv) { pthread_t thread, thread2; int rc=0; char *threadData; printf("Enter Testcase - %s\n", argv[0]); Qp0zUprintf("Tracing Testcase Entry\n"); printf("Create two threads\n"); Qp0zUprintf("Tracing creation of two threads\n"); threadData = (char *)malloc(THREADDATAMAX); sprintf(threadData, "50%% Cotton, 50%% Polyester"); rc = pthread_create(&thread, NULL, theThread, threadData); if (rc) { printf("Failed to create a %s thread\n", threadData); exit(EXIT_FAILURE); } threadData = (char *)malloc(THREADDATAMAX); sprintf(threadData, "Lacquered Camel Hair"); rc = pthread_create(&thread2, NULL, theThread, threadData); if (rc) { printf("Failed to create a %s thread\n", threadData); exit(EXIT_FAILURE); } printf("Wait for threads to complete\n"); rc = pthread_join(thread, NULL); if (rc) { printf("Failed pthread_join() 1\n"); exit(EXIT_FAILURE); } rc = pthread_join(thread2, NULL); if (rc) { printf("Failed pthread_join() 2\n"); exit(EXIT_FAILURE); } printf("Testcase complete\n"); Qp0zUprintf("Tracing completion of the testcase rc=%d\n", rc); return 0; }
Trace Output:
This trace output was generated after the test case was run by using the CL command DMPUSRTRC JOB(100465/USER/TPZSTK0) OUTPUT(*STDOUT). The above example program ran as job 100465/USER/TPZSTK0.
Note the following in the trace output:
- Each trace record is indented by several spaces to aid in readability.
Trace records from different threads have different indentation levels.
- Each trace record is identified by the hexadecimal thread ID, a colon, and a timestamp. The timestamp can be used to aid in debugging of waiting or looping threads. For example, the third trace record shown below, (the Tracing Testcase Entry trace point) was created by thread 0x16, and occurred 0.841456 seconds after the last full date and time label. This means that the trace record was created on 5 January 1998 at 16:32:23.841456. A full date and time label is placed between those trace points that occur during different whole seconds.
User Trace Dump for job 100465/USER/TPZSTK0. Size: 300K, Wrapped 0 times. --- 01/05/1998 16:32:23 --- 00000016:841456 Tracing Testcase Entry 00000016:842176 Tracing creation of two threads 00000017:850328 function bar(): Hit an error condition! 00000017:850552 Stack Dump For Current Thread 00000017:850752 Stack: 50% Cotton, 50% Polyester 00000018:853288 function bar(): Hit an error condition! 00000018:853512 Stack Dump For Current Thread 00000018:853712 Stack: Lacquered Camel Hair 00000018:888752 Stack: Library / Program Module Stmt Procedure 00000017:889400 Stack: Library / Program Module Stmt Procedure 00000017:904848 Stack: QSYS / QLESPI QLECRTTH 774 : LE_Create_Thread2__FP12crtth_parm_t 00000017:905088 Stack: QSYS / QP0WPTHR QP0WPTHR 1004 : pthread_create_part2 00000017:905312 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : theThread 00000017:905528 Stack: QP0WTEST / TPZSTK0 TPZSTK0 1 : foo 00000017:905744 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : bar 00000017:905960 Stack: QSYS / QP0ZCPA QP0ZUDBG 85 : Qp0zDumpStack 00000017:906184 Stack: QSYS / QP0ZSCPA QP0ZSCPA 274 : Qp0zSUDumpStack 00000017:906408 Stack: QSYS / QP0ZSCPA QP0ZSCPA 285 : Qp0zSUDumpTargetStack 00000017:906536 Stack: Completed 00000018:908504 Stack: QSYS / QLESPI QLECRTTH 774 : LE_Create_Thread2__FP12crtth_parm_t 00000018:908744 Stack: QSYS / QP0WPTHR QP0WPTHR 1004 : pthread_create_part2 00000018:908960 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : theThread 00000018:909168 Stack: QP0WTEST / TPZSTK0 TPZSTK0 1 : foo 00000018:909384 Stack: QP0WTEST / TPZSTK0 TPZSTK0 2 : bar 00000018:909592 Stack: QSYS / QP0ZCPA QP0ZUDBG 85 : Qp0zDumpStack 00000018:909816 Stack: QSYS / QP0ZSCPA QP0ZSCPA 274 : Qp0zSUDumpStack 00000018:910032 Stack: QSYS / QP0ZSCPA QP0ZSCPA 285 : Qp0zSUDumpTargetStack 00000018:910168 Stack: Completed 00000016:912792 Tracing completion of the testcase rc=0 Press ENTER to end terminal session.
API introduced: V4R3
[ Back to top | Problem Management APIs | APIs by category ]