Red Hat Enterprise Linux 6.8 SystemTap Tapset Reference
Transcript of Red Hat Enterprise Linux 6.8 SystemTap Tapset Reference
Red Hat Enterprise Linux 6
SystemTap Tapset Reference
For SystemTap in Red Hat Enterprise Linux 6
Last Updated: 2017-10-20
Red Hat Enterprise Linux 6 SystemTap Tapset Reference
For SystemTap in Red Hat Enterprise Linux 6
Robert KrátkýRed Hat Customer Content [email protected]
William CohenRed Hat Performance Tools
Don DomingoRed Hat Customer Content Services
Red Hat, Inc.
Edited by
Jacquelynn EastRed Hat Customer Content Services
Legal Notice
Copyright © 2010 Red Hat, Inc. and others.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0Unported License. If you distribute this document, or a modified version of it, you must provideattribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all RedHat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinitylogo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and othercountries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.
Java ® is a registered trademark of Oracle and/or its affiliates.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the UnitedStates and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union andother countries.
Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally relatedto or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marksor trademarks/service marks of the OpenStack Foundation, in the United States and othercountries and are used with the OpenStack Foundation's permission. We are not affiliated with,endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Abstract
The Tapset Reference Guide describes the most common tapset definitions users can apply toSystemTap scripts. All included tapsets documented in this guide are current as of the latestupstream version of SystemTap.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Table of Contents
PREFACE
CHAPTER 1. INTRODUCTION1.1. DOCUMENTATION GOALS
CHAPTER 2. TAPSET DEVELOPMENT GUIDELINES2.1. WRITING GOOD TAPSETS2.2. ELEMENTS OF A TAPSET
2.2.1. Tapset Files2.2.2. Namespace2.2.3. Comments and Documentation
CHAPTER 3. CONTEXT FUNCTIONSNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAX
26
2727
282829292929
32323232323232323232323232333333333333333333333333333334343434343434343434343434
Table of Contents
1
DESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTS
3435353535353535353535353535353636363636363636363636363636373737373737373737373737373838383838383838383838
SystemTap Tapset Reference
2
GENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAME
3838393939393939393939393939393940404040404040404040404040404141414141414141414242424242424242424242424343
Table of Contents
3
SYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONPLEASE NOTENAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAX
4343434343434343444444444444444444444444444545454545454545454546464646464646464646474747474747474747474848
SystemTap Tapset Reference
4
DESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTS
4848484848484848484849494949494949494949494950505050505050505050505051515151515151515151515252525252525252
Table of Contents
5
GENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTS
5252525252535353535353535353535354545454545454545454545455555555555555555555555556565656565656565656565657
SystemTap Tapset Reference
6
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTION
CHAPTER 4. TIMESTAMP FUNCTIONSNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAX
575757575757575757575758585858585858585858585859595959
60606060606060606060606060616161616161616161616161
Table of Contents
7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIPTION
CHAPTER 5. TIME STRING UTILITY FUNCTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTION
CHAPTER 6. MEMORY TAPSETNAMESYNOPSISARGUMENTSNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSIS
61
626262626262
6363636363636363636464646464646464646465656565656565656566666666666666666667676767676767
SystemTap Tapset Reference
8
VALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSIS
676868686969696970707070707071717171717171
7272727272727272727272727373737373737373737373747474747474747474
Table of Contents
9
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTION
CHAPTER 7. TASK TIME TAPSETNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTS
74747575757575757575757575767676767676767676767677
787878787878787878787878797979797979797979797980808080
SystemTap Tapset Reference
10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTION
CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSETNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESDESCRIPTIONNAME
808080808080808181
82828282828282838383838383848484858585858585868686868687878787878787888888888888888989
Table of Contents
11
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESDESCRIPTIONCONTEXTNAMESYNOPSISVALUESDESCRIPTIONCONTEXTNAMESYNOPSISVALUESDESCRIPTIONCONTEXTNAMESYNOPSISVALUESDESCRIPTIONCONTEXTNAMESYNOPSISVALUESDESCRIPTIONCONTEXT
CHAPTER 9. SCSI TAPSETNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUES
CHAPTER 10. TTY TAPSETNAMESYNOPSISVALUES
89898989898989909090909090909090909191919191919191929292
93939393939393949494959595969696979797
99999999
SystemTap Tapset Reference
12
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUES
CHAPTER 11. NETWORKING TAPSETNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUES
999999
100100100101101101101101101102102102102102102103103103103103103104104104104104104
105105105105105105105106106106106106106106106106107107107107107107
Table of Contents
13
NAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXT
107107108108108108108108108109109109109109109109109109110110110110110110110111111111111111111111112112112112112112112113113113113113113114114114114114114114115
SystemTap Tapset Reference
14
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NAMESYNOPSISVALUESNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISARGUMENTS
CHAPTER 12. SOCKET TAPSETNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUES
115115115116116116116116116116117117117117117117117117117118118118118118118118118118118119
120120120120120120120121121121121121122122122122122123123123123123
Table of Contents
15
CONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAME
124124124124124124125125125125125125125125126126126126126126127127127127127128128128128128129129129129129130130130130130130130130131131131131131131132132132132
SystemTap Tapset Reference
16
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTS
CHAPTER 13. KERNEL PROCESS TAPSETNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUES
132132133133133133133133134134134134134134134134134134134134135135135135135135135135135135136136136
137137137137137137137137137137137137137138138138138138138
Table of Contents
17
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTION
CHAPTER 14. SIGNAL TAPSETNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTDESCRIPTIONWHICH MEANS THATNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSIS
138138138138138139139139139139139139
140140140140140141141141141141141142142142142142142143143143143143143144144144144144144145145145145145145145146146146146
SystemTap Tapset Reference
18
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUES
CHAPTER 15. DIRECTORY-ENTRY (DENTRY) TAPSETNAMESYNOPSISARGUMENTSDESCRIPTIONNAME
146146146146146147147147147147147148148148148148148149149149149149149149149150150150150151151151151151152152152152152152152153153153153153
154154154154154154
Table of Contents
19
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTION
CHAPTER 16. LOGGING TAPSETNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTION
CHAPTER 17. RANDOM FUNCTIONS TAPSETNAMESYNOPSISARGUMENTS
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONS TAPSETNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAME
154154154154154154155155155155155
156156156156156156156156156156156157157157157157157157157157157157157158
159159159159
160160160160160160160160160160160161
SystemTap Tapset Reference
20
SYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTION
161161161161161161161161161162162162162162162162162162162162162163163163163163163163163163163163164164164164164164164164164164164165165165165165165165165165165
Table of Contents
21
NAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTS
166166166166166166166166167167167167167167167167167167168168168168168168168168168168168168169169169169169169169169169169169169170170170170170170170170170170170
SystemTap Tapset Reference
22
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL SYNTAXDESCRIPTION
CHAPTER 19. A COLLECTION OF STANDARD STRING FUNCTIONSNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAX
171171
172172172172172172172172172172173173173173173173173173173173174174174174174174174174174174175175175175175175175175175176176176176176176176176176176177
Table of Contents
23
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIPTION
CHAPTER 20. UTILITY FUNCTIONS FOR USING ANSI CONTROL CHARS IN LOGSNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTION
177
178178178178178178178178178178178178179179179179179179179179179180180180180180180180180180180180180180181181181181181181181181181181181181182182182182182
SystemTap Tapset Reference
24
NAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTION
182182182182182
Table of Contents
25
PREFACE
SystemTap Tapset Reference
26
CHAPTER 1. INTRODUCTIONSystemTap provides free software (GPL) infrastructure to simplify the gathering of information aboutthe running Linux system. This assists diagnosis of a performance or functional problem. SystemTapeliminates the need for the developer to go through the tedious and disruptive instrument, recompile,install, and reboot sequence that may be otherwise required to collect data.
SystemTap provides a simple command line interface and scripting language for writinginstrumentation for a live, running kernel. This instrumentation uses probe points and functionsprovided in the tapset library.
Simply put, tapsets are scripts that encapsulate knowledge about a kernel subsystem into pre-writtenprobes and functions that can be used by other scripts. Tapsets are analogous to libraries for Cprograms. They hide the underlying details of a kernel area while exposing the key information neededto manage and monitor that aspect of the kernel. They are typically developed by kernel subject-matter experts.
A tapset exposes the high-level data and state transitions of a subsystem. For the most part, goodtapset developers assume that SystemTap users know little to nothing about the kernel subsystem'slow-level details. As such, tapset developers write tapsets that help ordinary SystemTap users writemeaningful and useful SystemTap scripts.
1.1. DOCUMENTATION GOALS
This guide aims to document SystemTap's most useful and common tapset entries; it also containsguidelines on proper tapset development and documentation. The tapset definitions contained in thisguide are extracted automatically from properly-formatted comments in the code of each tapset file.As such, any revisions to the definitions in this guide should be applied directly to their respectivetapset file.
CHAPTER 1. INTRODUCTION
27
CHAPTER 2. TAPSET DEVELOPMENT GUIDELINESThis chapter describes the upstream guidelines on proper tapset documentation. It also containsinformation on how to properly document your tapsets, to ensure that they are properly defined in thisguide.
2.1. WRITING GOOD TAPSETS
The first step to writing good tapsets is to create a simple model of your subject area. For example, amodel of the process subsystem might include the following:
Key Data
process ID
parent process ID
process group ID
State Transitions
forked
exec'd
running
stopped
terminated
NOTE
Both lists are examples, and are not meant to represent a complete list.
Use your subsystem expertise to find probe points (function entries and exits) that expose theelements of the model, then define probe aliases for those points. Be aware that some state transitionscan occur in more than one place. In those cases, an alias can place a probe in multiple locations.
For example, process execs can occur in either the do_execve() or the compat_do_execve()functions. The following alias inserts probes at the beginning of those functions:
Try to place probes on stable interfaces (i.e., functions that are unlikely to change at the interfacelevel) whenever possible. This will make the tapset less likely to break due to kernel changes. Wherekernel version or architecture dependencies are unavoidable, use preprocessor conditionals (see the stap(1) man page for details).
Fill in the probe bodies with the key data available at the probe points. Function entry probes canaccess the entry parameters specified to the function, while exit probes can access the entryparameters and the return value. Convert the data into meaningful forms where appropriate (e.g.,
probe kprocess.exec = kernel.function("do_execve"),kernel.function("compat_do_execve") {probe body}
SystemTap Tapset Reference
28
bytes to kilobytes, state values to strings, etc).
You may need to use auxiliary functions to access or convert some of the data. Auxiliary functionsoften use embedded C to do things that cannot be done in the SystemTap language, like accessstructure fields in some contexts, follow linked lists, etc. You can use auxiliary functions defined inother tapsets or write your own.
In the following example, copy_process() returns a pointer to the task_struct for the newprocess. Note that the process ID of the new process is retrieved by calling task_pid() and passing itthe task_struct pointer. In this case, the auxiliary function is an embedded C function defined in task.stp.
It is not advisable to write probes for every function. Most SystemTap users will not need orunderstand them. Keep your tapsets simple and high-level.
2.2. ELEMENTS OF A TAPSET
The following sections describe the most important aspects of writing a tapset. Most of the contentherein is suitable for developers who wish to contribute to SystemTap's upstream library of tapsets.
2.2.1. Tapset Files
Tapset files are stored in src/tapset/ of the SystemTap GIT directory. Most tapset files are kept atthat level. If you have code that only works with a specific architecture or kernel version, you maychoose to put your tapset in the appropriate subdirectory.
Installed tapsets are located in /usr/share/systemtap/tapset/ or /usr/local/share/systemtap/tapset.
Personal tapsets can be stored anywhere. However, to ensure that SystemTap can use them, use -I tapset_directory to specify their location when invoking stap.
2.2.2. Namespace
Probe alias names should take the form tapset_name.probe_name. For example, the probe forsending a signal could be named signal.send.
Global symbol names (probes, functions, and variables) should be unique accross all tapsets. This helpsavoid namespace collisions in scripts that use multiple tapsets. To ensure this, use tapset-specificprefixes in your global symbols.
Internal symbol names should be prefixed with an underscore (_).
2.2.3. Comments and Documentation
All probes and functions should include comment blocks that describe their purpose, the data theyprovide, and the context in which they run (e.g. interrupt, process, etc). Use comments in areas whereyour intent may not be clear from reading the code.
probe kprocess.create = kernel.function("copy_process").return { task = $return new_pid = task_pid(task)}
CHAPTER 2. TAPSET DEVELOPMENT GUIDELINES
29
Note that specially-formatted comments are automatically extracted from most tapsets and includedin this guide. This helps ensure that tapset contributors can write their tapset and document it in thesame place. The specified format for documenting tapsets is as follows:
For example:
To override the automatically-generated Synopsis content, use:
For example:
/** * probe tapset.name - Short summary of what the tapset does. * @argument: Explanation of argument. * @argument2: Explanation of argument2. Probes can have multiple arguments. * * Context: * A brief explanation of the tapset context. * Note that the context should only be 1 paragraph short. * * Text that will appear under "Description." * * A new paragraph that will also appear under the heading "Description". * * Header: * A paragraph that will appear under the heading "Header". **/
/** * probe vm.write_shared_copy- Page copy for shared page write. * @address: The address of the shared write. * @zero: Boolean indicating whether it is a zero page * (can do a clear instead of a copy). * * Context: * The process attempting the write. * * Fires when a write to a shared page requires a page copy. This is * always preceded by a vm.shared_write. **/
* Synopsis: * New Synopsis string *
/** * probe signal.handle - Fires when the signal handler is invoked * @sig: The signal number that invoked the signal handler * * Synopsis: * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka, * sigset_t *oldset, struct pt_regs * regs)</programlisting> */
SystemTap Tapset Reference
30
It is recommended that you use the <programlisting> tag in this instance, since overriding the Synopsis content of an entry does not automatically form the necessary tags.
For the purposes of improving the DocBook XML output of your comments, you can also use thefollowing XML tags in your comments:
command
emphasis
programlisting
remark (tagged strings will appear in Publican beta builds of the document)
CHAPTER 2. TAPSET DEVELOPMENT GUIDELINES
31
CHAPTER 3. CONTEXT FUNCTIONSThe context functions provide additional information about where an event occurred. These functionscan provide information such as a backtrace to where the event occurred and the current registervalues for the processor.
NAMEfunction::print_regs — Print a register dump.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXprint_regs
DESCRIPTIONThis function prints a register dump.
NAMEfunction::execname — Returns the execname of a target process (or group of processes).
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXexecname:string
DESCRIPTIONReturns the execname of a target process (or group of processes).
NAMEfunction::pid — Returns the ID of a target process.
SYNOPSIS
function print_regs()
function execname:string()
function pid:long()
SystemTap Tapset Reference
32
ARGUMENTSNone
GENERAL SYNTAXpid:long
DESCRIPTIONThis function returns the ID of a targer process.
NAMEfunction::tid — Returns the thread ID of a target process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXtid:long
DESCRIPTIONThis function returns the thread ID of the target process.
NAMEfunction::ppid — Returns the process ID of a target process's parent process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXppid:long
DESCRIPTIONThis function return the process ID of the target proccess's parent process.
NAMEfunction::pgrp — Returns the process group ID of the current process.
function tid:long()
function ppid:long()
CHAPTER 3. CONTEXT FUNCTIONS
33
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXpgrp:long
DESCRIPTIONThis function returns the process group ID of the current process.
NAMEfunction::sid — Returns the session ID of the current process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXsid:long
DESCRIPTIONThe session ID of a process is the process group ID of the session leader. Session ID is stored in thesignal_struct since Kernel 2.6.0.
NAMEfunction::pexecname — Returns the execname of a target process's parent process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXpexecname:string
DESCRIPTIONThis function returns the execname of a target process's parent procces.
function pgrp:long()
function sid:long()
function pexecname:string()
SystemTap Tapset Reference
34
NAMEfunction::gid — Returns the group ID of a target process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXgid:long
DESCRIPTIONThis function returns the group ID of a target process.
NAMEfunction::egid — Returns the effective gid of a target process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXegid:long
DESCRIPTIONThis function returns the effective gid of a target process
NAMEfunction::uid — Returns the user ID of a target process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXuid:long
function gid:long()
function egid:long()
function uid:long()
CHAPTER 3. CONTEXT FUNCTIONS
35
DESCRIPTIONThis function returns the user ID of the target process.
NAMEfunction::euid — Return the effective uid of a target process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXeuid:long
DESCRIPTIONReturns the effective user ID of the target process.
NAMEfunction::is_myproc — Determines if the current probe point has occurred in the user's own process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXis_myproc:long
DESCRIPTIONThis function returns 1 if the current probe point has occurred in the user's own process.
NAMEfunction::cpu — Returns the current cpu number.
SYNOPSIS
ARGUMENTS
function euid:long()
function is_myproc:long()
function cpu:long()
SystemTap Tapset Reference
36
None
GENERAL SYNTAXcpu:long
DESCRIPTIONThis function returns the current cpu number.
NAMEfunction::pp — Returns the active probe point.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXpp:string
DESCRIPTIONThis function returns the fully-resolved probe point associated with a currently running probe handler,including alias and wild-card expansion effects. Context: The current probe point.
NAMEfunction::registers_valid — Determines validity of register and u_register in current context.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXregisters_valid:long
DESCRIPTIONThis function returns 1 if register and u_register can be used in the current context, or 0otherwise. For example, registers_valid returns 0 when called from a begin or end probe.
NAMEfunction::user_mode — Determines if probe point occurs in user-mode.
function pp:string()
function registers_valid:long()
CHAPTER 3. CONTEXT FUNCTIONS
37
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXuser_mode:long
Return 1 if the probe point occurred in user-mode.
NAMEfunction::is_return — Whether the current probe context is a return probe.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXis_return:long
DESCRIPTIONReturns 1 if the current probe context is a return probe, returns 0 otherwise.
NAMEfunction::target — Return the process ID of the target process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXtarget:long
DESCRIPTIONThis function returns the process ID of the target process. This is useful in conjunction with the -x PIDor -c CMD command-line options to stap. An example of its use is to create scripts that filter on aspecific process.
function user_mode:long()
function is_return:long()
function target:long()
SystemTap Tapset Reference
38
NAMEfunction::module_name — The module name of the current script.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXmodule_name:string
DESCRIPTIONThis function returns the name of the stap module. Either generated randomly (stap_[0-9a-f]+_[0-9a-f]+) or set by stap -m <module_name>.
NAMEfunction::stp_pid — The process id of the stapio process.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXstp_pid:long
DESCRIPTIONThis function returns the process id of the stapio process that launched this script. There could beother SystemTap scripts and stapio processes running on the system.
NAMEfunction::stack_size — Return the size of the kernel stack.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXstack_size:long
function module_name:string()
function stp_pid:long()
function stack_size:long()
CHAPTER 3. CONTEXT FUNCTIONS
39
DESCRIPTIONThis function returns the size of the kernel stack.
NAMEfunction::stack_used — Returns the amount of kernel stack used.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXstack_used:long
DESCRIPTIONThis function determines how many bytes are currently used in the kernel stack.
NAMEfunction::stack_unused — Returns the amount of kernel stack currently available.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXstack_unused:long
DESCRIPTIONThis function determines how many bytes are currently available in the kernel stack.
NAMEfunction::uaddr — User space address of current running task. EXPERIMENTAL.
SYNOPSIS
ARGUMENTS
function stack_used:long()
function stack_unused:long()
function uaddr:long()
SystemTap Tapset Reference
40
None
GENERAL SYNTAXuaddr:long
DESCRIPTIONReturns the address in userspace that the current task was at when the probe occurred. When thecurrent running task isn't a user space thread, or the address cannot be found, zero is returned. Can beused to see where the current task is combined with usymname or symdata. Often the task will be inthe VDSO where it entered the kernel. FIXME - need VDSO tracking support #10080.
NAMEfunction::cmdline_args — Fetch command line arguments from current process
SYNOPSIS
ARGUMENTS
n
First argument to get (zero is the command itself)
m
Last argument to get (or minus one for all arguments after n)
delim
String to use to delimit arguments when more than one.
GENERAL SYNTAXcmdline_args:string(n:long, m:long, delim:string)
DESCRIPTIONReturns arguments from the current process starting with argument number n, up to argument m. Ifthere are less than n arguments, or the arguments cannot be retrieved from the current process, theempty string is returned. If m is smaller than n then all arguments starting from argument n arereturned. Argument zero is traditionally the command itself.
NAMEfunction::cmdline_arg — Fetch a command line argument.
SYNOPSIS
function cmdline_args:string(n:long,m:long,delim:string)
function cmdline_arg:string(n:long)
CHAPTER 3. CONTEXT FUNCTIONS
41
ARGUMENTS
n
Argument to get (zero is the command itself)
GENERAL SYNTAXcmdline_arg:string(n:long)
DESCRIPTIONReturns argument the requested argument from the current process or the empty string when thereare not that many arguments or there is a problem retrieving the argument. Argument zero istraditionally the command itself.
NAMEfunction::cmdline_str — Fetch all command line arguments from current process
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXcmdline_str:string
DESCRIPTIONReturns all arguments from the current process delimited by spaces. Returns the empty string whenthe arguments cannot be retrieved.
NAMEfunction::env_var — Fetch environment variable from current process
SYNOPSIS
ARGUMENTS
name
Name of the environment variable to fetch
GENERAL SYNTAXevn_var:string(name:string)
function cmdline_str:string()
function env_var:string(name:string)
SystemTap Tapset Reference
42
DESCRIPTIONReturns the contents of the specified environment value for the current process. If the variable isn't setan empty string is returned.
NAMEfunction::print_stack — Print out kernel stack from string.
SYNOPSIS
ARGUMENTS
stk
String with list of hexadecimal addresses.
GENERAL SYNTAXprint_stack(stk:string)
DESCRIPTIONThis function performs a symbolic lookup of the addresses in the given string, which is assumed to bethe result of a prior call to backtrace.
Print one line per address, including the address, the name of the function containing the address, andan estimate of its position within that function. Return nothing.
NAMEfunction::sprint_stack — Return stack for kernel addresses from string. EXPERIMENTAL!
SYNOPSIS
ARGUMENTS
stk
String with list of hexadecimal (kernel) addresses.
DESCRIPTIONPerform a symbolic lookup of the addresses in the given string, which is assumed to be the result of aprior call to backtrace.
Returns a simple backtrace from the given hex string. One line per address. Includes the symbol name(or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset from thestart of the function if found, otherwise the offset will be added to the module (if found, between
function print_stack(stk:string)
function sprint_stack:string(stk:string)
CHAPTER 3. CONTEXT FUNCTIONS
43
brackets). Returns the backtrace as string (each line terminated by a newline character). Note that thereturned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_stack.
NAMEfunction::probefunc — Return the probe point's function name, if known.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXprobefunc:string
DESCRIPTIONThis function returns the name of the function being probed. It will do this based on the probe pointstring as returned by pp.
PLEASE NOTEthis function is deprecated, please use symname and/or usymname. This function might return afunction name based on the current address if the probe point context couldn't be parsed.
NAMEfunction::probemod — Return the probe point's kernel module name.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXprobemod:string
DESCRIPTIONThis funciton returns the name of the kernel module containing the probe point, if known.
NAMEfunction::modname — Return the kernel module name loaded at the address.
SYNOPSIS
function probefunc:string()
function probemod:string()
SystemTap Tapset Reference
44
ARGUMENTS
addr
The address.
DESCRIPTIONReturns the module name associated with the given address if known. If not known it will return thestring “<unknown>”. If the address was not in a kernel module, but in the kernel itself, then the string“kernel” will be returned.
NAMEfunction::symname — Return the kernel symbol associated with the given address.
SYNOPSIS
ARGUMENTS
addr
The address to translate.
GENERAL SYNTAXsymname:string(addr:long)
DESCRIPTIONReturns the (function) symbol name associated with the given address if known. If not known it willreturn the hex string representation of addr.
NAMEfunction::symdata — Return the kernel symbol and module offset for the address.
SYNOPSIS
ARGUMENTS
addr
The address to translate.
function modname:string(addr:long)
function symname:string(addr:long)
function symdata:string(addr:long)
CHAPTER 3. CONTEXT FUNCTIONS
45
GENERAL SYNTAXsymdata:string(addr:long)
DESCRIPTIONReturns the (function) symbol name associated with the given address if known, the offset from thestart and size of the symbol, plus module name (between brackets). If symbol is unknown, but module isknown, the offset inside the module, plus the size of the module is added. If any element is not known itwill be omitted and if the symbol name is unknown it will return the hex string for the given address.
NAMEfunction::usymname — Return the symbol of an address in the current task. EXPERIMENTAL!
SYNOPSIS
ARGUMENTS
addr
The address to translate.
DESCRIPTIONReturns the (function) symbol name associated with the given address if known. If not known it willreturn the hex string representation of addr.
NAMEfunction::usymdata — Return the symbol and module offset of an address. EXPERIMENTAL!
SYNOPSIS
ARGUMENTS
addr
The address to translate.
DESCRIPTIONReturns the (function) symbol name associated with the given address in the current task if known, theoffset from the start and the size of the symbol, plus the module name (between brackets). If symbol isunknown, but module is known, the offset inside the module, plus the size of the module is added. If anyelement is not known it will be omitted and if the symbol name is unknown it will return the hex stringfor the given address.
function usymname:string(addr:long)
function usymdata:string(addr:long)
SystemTap Tapset Reference
46
NAMEfunction::print_ustack — Print out stack for the current task from string. EXPERIMENTAL!
SYNOPSIS
ARGUMENTS
stk
String with list of hexadecimal addresses for the current task.
DESCRIPTIONPerform a symbolic lookup of the addresses in the given string, which is assumed to be the result of aprior call to ubacktrace for the current task.
Print one line per address, including the address, the name of the function containing the address, andan estimate of its position within that function. Return nothing.
NAMEfunction::sprint_ustack — Return stack for the current task from string. EXPERIMENTAL!
SYNOPSIS
ARGUMENTS
stk
String with list of hexadecimal addresses for the current task.
DESCRIPTIONPerform a symbolic lookup of the addresses in the given string, which is assumed to be the result of aprior call to ubacktrace for the current task.
Returns a simple backtrace from the given hex string. One line per address. Includes the symbol name(or hex address if symbol couldn't be resolved) and module name (if found). Includes the offset from thestart of the function if found, otherwise the offset will be added to the module (if found, betweenbrackets). Returns the backtrace as string (each line terminated by a newline character). Note that thereturned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_ustack.
NAMEfunction::print_backtrace — Print stack back trace
SYNOPSIS
function print_ustack(stk:string)
function sprint_ustack:string(stk:string)
CHAPTER 3. CONTEXT FUNCTIONS
47
ARGUMENTSNone
GENERAL SYNTAXprint_backtrace
DESCRIPTIONThis function isEquivalent to print_stack(backtrace), except that deeper stack nesting may besupported. The function does not return a value.
NAMEfunction::sprint_backtrace — Return stack back trace as string. EXPERIMENTAL!
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns a simple (kernel) backtrace. One line per address. Includes the symbol name (or hex address ifsymbol couldn't be resolved) and module name (if found). Includes the offset from the start of thefunction if found, otherwise the offset will be added to the module (if found, between brackets). Returnsthe backtrace as string (each line terminated by a newline character). Note that the returned stack willbe truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_backtrace. Equivalentto sprint_stack(backtrace), but more efficient (no need to translate between hex strings and finalbacktrace string).
NAMEfunction::backtrace — Hex backtrace of current stack
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXbacktrace:string
DESCRIPTION
function print_backtrace()
function sprint_backtrace:string()
function backtrace:string()
SystemTap Tapset Reference
48
This function returns a string of hex addresses that are a backtrace of the stack. Output may betruncated as as per maximum string length (MAXSTRINGLEN).
NAMEfunction::task_backtrace — Hex backtrace of an arbitrary task
SYNOPSIS
ARGUMENTS
task
pointer to task_struct
GENERAL SYNTAXtask_backtrace:string(task:long)
DESCRIPTIONThis function returns a string of hex addresses that are a backtrace of the stack of a particular taskOutput may be truncated as per maximum string length.
NAMEfunction::caller — Return name and address of calling function
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXcaller:string
DESCRIPTIONThis function returns the address and name of the calling function. This is equivalent to calling:sprintf(“s 0xx”, symname(caller_addr, caller_addr)) Works only for return probes at this time.
NAMEfunction::caller_addr — Return caller address
SYNOPSIS
function task_backtrace:string(task:long)
function caller:string()
CHAPTER 3. CONTEXT FUNCTIONS
49
ARGUMENTSNone
GENERAL SYNTAXcaller_addr:long
DESCRIPTIONThis function returns the address of the calling function. Works only for return probes at this time.
NAMEfunction::print_ubacktrace — Print stack back trace for current task. EXPERIMENTAL!
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONEquivalent to print_ustack(ubacktrace), except that deeper stack nesting may be supported. Returnsnothing.
NOTETo get (full) backtraces for user space applications and shared shared libraries not mentioned in thecurrent script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
NAMEfunction::sprint_ubacktrace — Return stack back trace for current task as string. EXPERIMENTAL!
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns a simple backtrace for the current task. One line per address. Includes the symbol name (orhex address if symbol couldn't be resolved) and module name (if found). Includes the offset from thestart of the function if found, otherwise the offset will be added to the module (if found, betweenbrackets). Returns the backtrace as string (each line terminated by a newline character). Note that the
function caller_addr:long()
function print_ubacktrace()
function sprint_ubacktrace:string()
SystemTap Tapset Reference
50
returned stack will be truncated to MAXSTRINGLEN, to print fuller and richer stacks use print_ubacktrace. Equivalent to sprint_ustack(ubacktrace), but more efficient (no need totranslate between hex strings and final backtrace string).
NOTETo get (full) backtraces for user space applications and shared shared libraries not mentioned in thecurrent script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
NAMEfunction::print_ubacktrace_brief — Print stack back trace for current task. EXPERIMENTAL!
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONEquivalent to print_ubacktrace, but output for each symbol is shorter (just name and offset, or justthe hex address of no symbol could be found).
NOTETo get (full) backtraces for user space applications and shared shared libraries not mentioned in thecurrent script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
NAMEfunction::ubacktrace — Hex backtrace of current task stack. EXPERIMENTAL!
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturn a string of hex addresses that are a backtrace of the stack of the current task. Output may betruncated as per maximum string length. Returns empty string when current probe point cannotdetermine user backtrace.
NOTETo get (full) backtraces for user space applications and shared shared libraries not mentioned in thecurrent script run stap with -d /path/to/exe-or-so and/or add --ldd to load all needed unwind data.
function print_ubacktrace_brief()
function ubacktrace:string()
CHAPTER 3. CONTEXT FUNCTIONS
51
NAMEfunction::task_current — The current task_struct of the current task.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXtask_current:long
DESCRIPTIONThis function returns the task_struct representing the current process. This address can be passed tothe various task_*() functions to extract more task-specific data.
NAMEfunction::task_parent — The task_struct of the parent task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_parent:long(task:long)
DESCRIPTIONThis function returns the parent task_struct of the given task. This address can be passed to thevarious task_*() functions to extract more task-specific data.
NAMEfunction::task_state — The state of the task.
SYNOPSIS
ARGUMENTS
task
function task_current:long()
function task_parent:long(task:long)
function task_state:long(task:long)
SystemTap Tapset Reference
52
task
task_struct pointer.
GENERAL SYNTAXtask_state:long(task:long)
DESCRIPTIONReturn the state of the given task, one of: TASK_RUNNING (0), TASK_INTERRUPTIBLE (1),TASK_UNINTERRUPTIBLE (2), TASK_STOPPED (4), TASK_TRACED (8), EXIT_ZOMBIE (16),EXIT_DEAD (32).
NAMEfunction::task_execname — The name of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_execname:string(task:long)
DESCRIPTIONReturn the name of the given task.
NAMEfunction::task_pid — The process identifier of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_pid:long (task:long)
function task_execname:string(task:long)
function task_pid:long(task:long)
CHAPTER 3. CONTEXT FUNCTIONS
53
DESCRIPTIONThis fucntion returns the process id of the given task.
NAMEfunction::pid2task — The task_struct of the given process identifier.
SYNOPSIS
ARGUMENTS
pid
Process identifier.
DESCRIPTIONReturn the task struct of the given process id.
NAMEfunction::pid2execname — The name of the given process identifier.
SYNOPSIS
ARGUMENTS
pid
Process identifier.
DESCRIPTIONReturn the name of the given process id.
NAMEfunction::task_tid — The thread identifier of the task.
SYNOPSIS
ARGUMENTS
task
function pid2task:long(pid:long)
function pid2execname:string(pid:long)
function task_tid:long(task:long)
SystemTap Tapset Reference
54
task
task_struct pointer.
GENERAL SYNTAXtask_tid:long(task:long)
DESCRIPTIONThis function returns the thread id of the given task.
NAMEfunction::task_gid — The group identifier of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_gid:long(task:long)
DESCRIPTIONThis function returns the group id of the given task.
NAMEfunction::task_egid — The effective group identifier of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_egid:long(task:long)
DESCRIPTIONThis function returns the effective group id of the given task.
function task_gid:long(task:long)
function task_egid:long(task:long)
CHAPTER 3. CONTEXT FUNCTIONS
55
NAMEfunction::task_uid — The user identifier of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_uid:long(task:long)
DESCRIPTIONThis function returns the user id of the given task.
NAMEfunction::task_euid — The effective user identifier of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_euid:long(task:long)
DESCRIPTIONThis function returns the effective user id of the given task.
NAMEfunction::task_prio — The priority value of the task.
SYNOPSIS
function task_uid:long(task:long)
function task_euid:long(task:long)
function task_prio:long(task:long)
SystemTap Tapset Reference
56
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_prio:long(task:long)
DESCRIPTIONThis function returns the priority value of the given task.
NAMEfunction::task_nice — The nice value of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_nice:long(task:long)
DESCRIPTIONThis function returns the nice value of the given task.
NAMEfunction::task_cpu — The scheduled cpu of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_cpu:long(task:long)
function task_nice:long(task:long)
function task_cpu:long(task:long)
CHAPTER 3. CONTEXT FUNCTIONS
57
DESCRIPTIONThis function returns the scheduled cpu for the given task.
NAMEfunction::task_open_file_handles — The number of open files of the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_open_file_handles:long(task:long)
DESCRIPTIONThis function returns the number of open file handlers for the given task.
NAMEfunction::task_max_file_handles — The max number of open files for the task.
SYNOPSIS
ARGUMENTS
task
task_struct pointer.
GENERAL SYNTAXtask_max_file_handles:long(task:long)
DESCRIPTIONThis function returns the maximum number of file handlers for the given task.
NAMEfunction::pn — Returns the active probe name.
function task_open_file_handles:long(task:long)
function task_max_file_handles:long(task:long)
SystemTap Tapset Reference
58
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXpn:string
DESCRIPTIONThis function returns the script-level probe point associated with a currently running probe handler,including wild-card expansion effects. Context: The current probe point.
function pn:string()
CHAPTER 3. CONTEXT FUNCTIONS
59
CHAPTER 4. TIMESTAMP FUNCTIONSEach timestamp function returns a value to indicate when a function is executed. These returnedvalues can then be used to indicate when an event occurred, provide an ordering for events, orcompute the amount of time elapsed between two time stamps.
NAMEfunction::get_cycles — Processor cycle count.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXget_cycles:long
DESCRIPTIONThis function returns the processor cycle counter value if available, else it returns zero. The cyclecounter is free running and unsynchronized on each processor. Thus, the order of events cannotdetermined by comparing the results of the get_cycles function on different processors.
NAMEfunction::gettimeofday_ns — Number of nanoseconds since UNIX epoch.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXgettimeofday_ns:long
DESCRIPTIONThis function returns the number of nanoseconds since the UNIX epoch.
NAMEfunction::gettimeofday_us — Number of microseconds since UNIX epoch.
SYNOPSIS
function get_cycles:long()
function gettimeofday_ns:long()
SystemTap Tapset Reference
60
ARGUMENTSNone
GENERAL SYNTAXgettimeofday_us:long
DESCRIPTIONThis function returns the number of microseconds since the UNIX epoch.
NAMEfunction::gettimeofday_ms — Number of milliseconds since UNIX epoch.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXgettimeofday_ms:long
DESCRIPTIONThis function returns the number of milliseconds since the UNIX epoch.
NAMEfunction::gettimeofday_s — Number of seconds since UNIX epoch.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXgettimeofday_s:long
DESCRIPTIONThis function returns the number of seconds since the UNIX epoch.
function gettimeofday_us:long()
function gettimeofday_ms:long()
function gettimeofday_s:long()
CHAPTER 4. TIMESTAMP FUNCTIONS
61
CHAPTER 5. TIME STRING UTILITY FUNCTIONUtility function to turn seconds since the epoch (as returned by the timestamp functiongettimeofday_s()) into a human readable date/time string.
NAMEfunction::ctime — Convert seconds since epoch into human readable date/time string.
SYNOPSIS
ARGUMENTS
epochsecs
Number of seconds since epoch (as returned by gettimeofday_s).
GENERAL SYNTAXctime:string(epochsecs:long)
DESCRIPTIONTakes an argument of seconds since the epoch as returned by gettimeofday_s. Returns a string ofthe form
“Wed Jun 30 21:49:08 1993 ”
The string will always be exactly 24 characters. If the time would be unreasonable far in the past(before what can be represented with a 32 bit offset in seconds from the epoch) the returned string willbe “a long, long time ago... ”. If the time would be unreasonable far in the future the returned string willbe “far far in the future... ” (both these strings are also 24 characters wide).
Note that the epoch (zero) corresponds to
“Thu Jan 1 00:00:00 1970 ”
The earliest full date given by ctime, corresponding to epochsecs -2147483648 is “Fri Dec 1320:45:52 1901”. The latest full date given by ctime, corresponding to epochsecs 2147483647 is “TueJan 19 03:14:07 2038”.
The abbreviations for the days of the week are ‘Sun’, ‘Mon’, ‘Tue’, ‘Wed’, ‘Thu’, ‘Fri’, and ‘Sat’. Theabbreviations for the months are ‘Jan’, ‘Feb’, ‘Mar’, ‘Apr’, ‘May’, ‘Jun’, ‘Jul’, ‘Aug’, ‘Sep’, ‘Oct’, ‘Nov’, and‘Dec’.
Note that the real C library ctime function puts a newline ('\n') character at the end of the string thatthis function does not. Also note that since the kernel has no concept of timezones, the returned timeis always in GMT.
function ctime:string(epochsecs:long)
SystemTap Tapset Reference
62
CHAPTER 6. MEMORY TAPSETThis family of probe points is used to probe memory-related events or query the memory usage of thecurrent process. It contains the following probe points:
NAMEfunction::vm_fault_contains — Test return value for page fault reason
SYNOPSIS
ARGUMENTS
value
The fault_type returned by vm.page_fault.return
test
The type of fault to test for (VM_FAULT_OOM or similar)
NAMEprobe::vm.pagefault — Records that a page fault occurred.
SYNOPSIS
VALUES
write_access
Indicates whether this was a write or read access; 1 indicates a write, while 0 indicates a read.
name
Name of the probe point
address
The address of the faulting memory access; i.e. the address that caused the page fault.
CONTEXTThe process which triggered the fault
NAME
function vm_fault_contains:long(value:long,test:long)
vm.pagefault
CHAPTER 6. MEMORY TAPSET
63
probe::vm.pagefault.return — Indicates what type of fault occurred.
SYNOPSIS
VALUES
name
Name of the probe point
fault_type
Returns either 0 (VM_FAULT_OOM) for out of memory faults, 2 (VM_FAULT_MINOR) for minorfaults, 3 (VM_FAULT_MAJOR) for major faults, or 1 (VM_FAULT_SIGBUS) if the fault was neitherOOM, minor fault, nor major fault.
NAMEfunction::addr_to_node — Returns which node a given address belongs to within a NUMA system.
SYNOPSIS
ARGUMENTS
addr
The address of the faulting memory access.
GENERAL SYNTAXaddr_to_node:long(addr:long)
DESCRIPTIONThis function accepts an address, and returns the node that the given address belongs to in a NUMAsystem.
NAMEprobe::vm.write_shared — Attempts at writing to a shared page.
SYNOPSIS
VALUES
name
vm.pagefault.return
function addr_to_node:long(addr:long)
vm.write_shared
SystemTap Tapset Reference
64
name
Name of the probe point
address
The address of the shared write.
CONTEXTThe context is the process attempting the write.
DESCRIPTIONFires when a process attempts to write to a shared page. If a copy is necessary, this will be followed bya vm.write_shared_copy.
NAMEprobe::vm.write_shared_copy — Page copy for shared page write.
SYNOPSIS
VALUES
name
Name of the probe point
zero
Boolean indicating whether it is a zero page (can do a clear instead of a copy).
address
The address of the shared write.
CONTEXTThe process attempting the write.
DESCRIPTIONFires when a write to a shared page requires a page copy. This is always preceded by avm.shared_write.
NAMEprobe::vm.mmap — Fires when an mmap is requested.
SYNOPSIS
vm.write_shared_copy
vm.mmap
CHAPTER 6. MEMORY TAPSET
65
VALUES
length
The length of the memory segment
name
Name of the probe point
address
The requested address
CONTEXTThe process calling mmap.
NAMEprobe::vm.munmap — Fires when an munmap is requested.
SYNOPSIS
VALUES
length
The length of the memory segment
name
Name of the probe point
address
The requested address
CONTEXTThe process calling munmap.
NAMEprobe::vm.brk — Fires when a brk is requested (i.e. the heap will be resized).
SYNOPSIS
VALUES
vm.munmap
vm.brk
SystemTap Tapset Reference
66
length
The length of the memory segment
name
Name of the probe point
address
The requested address
CONTEXTThe process calling brk.
NAMEprobe::vm.oom_kill — Fires when a thread is selected for termination by the OOM killer.
SYNOPSIS
VALUES
name
Name of the probe point
task
The task being killed
CONTEXTThe process that tried to consume excessive memory, and thus triggered the OOM.
NAMEprobe::vm.kmalloc — Fires when kmalloc is requested.
SYNOPSIS
VALUES
ptr
Pointer to the kmemory allocated
caller_function
vm.oom_kill
vm.kmalloc
CHAPTER 6. MEMORY TAPSET
67
Name of the caller function.
call_site
Address of the kmemory function.
gfp_flag_name
type of kmemory to allocate (in String format)
name
Name of the probe point
bytes_req
Requested Bytes
bytes_alloc
Allocated Bytes
gfp_flags
type of kmemory to allocate
NAMEprobe::vm.kmem_cache_alloc — Fires when \
SYNOPSIS
VALUES
ptr
Pointer to the kmemory allocated
caller_function
Name of the caller function.
call_site
Address of the function calling this kmemory function.
gfp_flag_name
Type of kmemory to allocate(in string format)
name
Name of the probe point
vm.kmem_cache_alloc
SystemTap Tapset Reference
68
bytes_req
Requested Bytes
bytes_alloc
Allocated Bytes
gfp_flags
type of kmemory to allocate
DESCRIPTIONkmem_cache_alloc is requested.
NAMEprobe::vm.kmalloc_node — Fires when kmalloc_node is requested.
SYNOPSIS
VALUES
ptr
Pointer to the kmemory allocated
caller_function
Name of the caller function.
call_site
Address of the function caling this kmemory function.
gfp_flag_name
Type of kmemory to allocate(in string format)
name
Name of the probe point
bytes_req
Requested Bytes
bytes_alloc
Allocated Bytes
gfp_flags
type of kmemory to allocate
vm.kmalloc_node
CHAPTER 6. MEMORY TAPSET
69
NAMEprobe::vm.kmem_cache_alloc_node — Fires when \
SYNOPSIS
VALUES
ptr
Pointer to the kmemory allocated
caller_function
Name of the caller function.
call_site
Address of the function calling this kmemory function.
gfp_flag_name
Type of kmemory to allocate(in string format)
name
Name of the probe point
bytes_req
Requested Bytes
bytes_alloc
Allocated Bytes
gfp_flags
type of kmemory to allocate
DESCRIPTIONkmem_cache_alloc_node is requested.
NAMEprobe::vm.kfree — Fires when kfree is requested.
SYNOPSIS
vm.kmem_cache_alloc_node
vm.kfree
SystemTap Tapset Reference
70
VALUES
ptr
Pointer to the kmemory allocated which is returned by kmalloc
caller_function
Name of the caller function.
call_site
Address of the function calling this kmemory function.
name
Name of the probe point
NAMEprobe::vm.kmem_cache_free — Fires when \
SYNOPSIS
VALUES
ptr
Pointer to the kmemory allocated which is returned by kmem_cache
caller_function
Name of the caller function.
call_site
Address of the function calling this kmemory function.
name
Name of the probe point
DESCRIPTIONkmem_cache_free is requested.
NAMEfunction::proc_mem_size — Total program virtual memory size in pages
SYNOPSIS
vm.kmem_cache_free
CHAPTER 6. MEMORY TAPSET
71
ARGUMENTSNone
DESCRIPTIONReturns the total virtual memory size in pages of the current process, or zero when there is no currentprocess or the number of pages couldn't be retrieved.
NAMEfunction::proc_mem_size_pid — Total program virtual memory size in pages
SYNOPSIS
ARGUMENTS
pid
The pid of process to examine
DESCRIPTIONReturns the total virtual memory size in pages of the given process, or zero when that process doesn'texist or the number of pages couldn't be retrieved.
NAMEfunction::proc_mem_rss — Program resident set size in pages
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns the resident set size in pages of the current process, or zero when there is no current processor the number of pages couldn't be retrieved.
NAMEfunction::proc_mem_rss_pid — Program resident set size in pages
SYNOPSIS
function proc_mem_size:long()
function proc_mem_size_pid:long(pid:long)
function proc_mem_rss:long()
SystemTap Tapset Reference
72
ARGUMENTS
pid
The pid of process to examine
DESCRIPTIONReturns the resident set size in pages of the given process, or zero when the process doesn't exist orthe number of pages couldn't be retrieved.
NAMEfunction::proc_mem_shr — Program shared pages (from shared mappings)
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns the shared pages (from shared mappings) of the current process, or zero when there is nocurrent process or the number of pages couldn't be retrieved.
NAMEfunction::proc_mem_shr_pid — Program shared pages (from shared mappings)
SYNOPSIS
ARGUMENTS
pid
The pid of process to examine
DESCRIPTIONReturns the shared pages (from shared mappings) of the given process, or zero when the processdoesn't exist or the number of pages couldn't be retrieved.
NAME
function proc_mem_rss_pid:long(pid:long)
function proc_mem_shr:long()
function proc_mem_shr_pid:long(pid:long)
CHAPTER 6. MEMORY TAPSET
73
function::proc_mem_txt — Program text (code) size in pages
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns the current process text (code) size in pages, or zero when there is no current process or thenumber of pages couldn't be retrieved.
NAMEfunction::proc_mem_txt_pid — Program text (code) size in pages
SYNOPSIS
ARGUMENTS
pid
The pid of process to examine
DESCRIPTIONReturns the given process text (code) size in pages, or zero when the process doesn't exist or thenumber of pages couldn't be retrieved.
NAMEfunction::proc_mem_data — Program data size (data + stack) in pages
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns the current process data size (data + stack) in pages, or zero when there is no current processor the number of pages couldn't be retrieved.
function proc_mem_txt:long()
function proc_mem_txt_pid:long(pid:long)
function proc_mem_data:long()
SystemTap Tapset Reference
74
NAMEfunction::proc_mem_data_pid — Program data size (data + stack) in pages
SYNOPSIS
ARGUMENTS
pid
The pid of process to examine
DESCRIPTIONReturns the given process data size (data + stack) in pages, or zero when the process doesn't exist orthe number of pages couldn't be retrieved.
NAMEfunction::mem_page_size — Number of bytes in a page for this architecture
SYNOPSIS
ARGUMENTSNone
NAMEfunction::bytes_to_string — Human readable string for given bytes
SYNOPSIS
ARGUMENTS
bytes
Number of bytes to translate.
DESCRIPTIONReturns a string representing the number of bytes (up to 1024 bytes), the number of kilobytes (whenless than 1024K) postfixed by 'K', the number of megabytes (when less than 1024M) postfixed by 'M' orthe number of gigabytes postfixed by 'G'. If representing K, M or G, and the number is amount is lessthan 100, it includes a '.' plus the remainer. The returned string will be 5 characters wide (padding withwhitespace at the front) unless negative or representing more than 9999G bytes.
function proc_mem_data_pid:long(pid:long)
function mem_page_size:long()
function bytes_to_string:string(bytes:long)
CHAPTER 6. MEMORY TAPSET
75
NAMEfunction::pages_to_string — Turns pages into a human readable string
SYNOPSIS
ARGUMENTS
pages
Number of pages to translate.
DESCRIPTIONMultiplies pages by page_size to get the number of bytes and returns the result of bytes_to_string.
NAMEfunction::proc_mem_string — Human readable string of current proc memory usage
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns a human readable string showing the size, rss, shr, txt and data of the memory used by thecurrent process. For example “size: 301m, rss: 11m, shr: 8m, txt: 52k, data: 2248k ”.
NAMEfunction::proc_mem_string_pid — Human readable string of process memory usage
SYNOPSIS
ARGUMENTS
pid
The pid of process to examine
function pages_to_string:string(pages:long)
function proc_mem_string:string()
function proc_mem_string_pid:string(pid:long)
SystemTap Tapset Reference
76
DESCRIPTIONReturns a human readable string showing the size, rss, shr, txt and data of the memory used by thegiven process. For example “size: 301m, rss: 11m, shr: 8m, txt: 52k, data: 2248k ”.
CHAPTER 6. MEMORY TAPSET
77
CHAPTER 7. TASK TIME TAPSETThis tapset defines utility functions to query time related properties of the current tasks, translatethose in miliseconds and human readable strings.
NAMEfunction::task_utime — User time of the current task
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns the user time of the current task in cputime. Does not include any time used by other tasks inthis process, nor does it include any time of the children of this task.
NAMEfunction::task_utime_tid — User time of the given task
SYNOPSIS
ARGUMENTS
tid
Thread id of the given task
DESCRIPTIONReturns the user time of the given task in cputime, or zero if the task doesn't exist. Does not includeany time used by other tasks in this process, nor does it include any time of the children of this task.
NAMEfunction::task_stime — System time of the current task
SYNOPSIS
ARGUMENTSNone
function task_utime:long()
function task_utime_tid:long(tid:long)
function task_stime:long()
SystemTap Tapset Reference
78
DESCRIPTIONReturns the system time of the current task in cputime. Does not include any time used by other tasksin this process, nor does it include any time of the children of this task.
NAMEfunction::task_stime_tid — System time of the given task
SYNOPSIS
ARGUMENTS
tid
Thread id of the given task
DESCRIPTIONReturns the system time of the given task in cputime, or zero if the task doesn't exist. Does not includeany time used by other tasks in this process, nor does it include any time of the children of this task.
NAMEfunction::cputime_to_msecs — Translates the given cputime into milliseconds
SYNOPSIS
ARGUMENTS
cputime
Time to convert to milliseconds.
NAMEfunction::msecs_to_string — Human readable string for given milliseconds
SYNOPSIS
ARGUMENTS
msecs
function task_stime_tid:long(tid:long)
function cputime_to_msecs:long(cputime:long)
function msecs_to_string:string(msecs:long)
CHAPTER 7. TASK TIME TAPSET
79
Number of milliseconds to translate.
DESCRIPTIONReturns a string representing the number of milliseconds as a human readable string consisting of“XmY.ZZZs”, where X is the number of minutes, Y is the number of seconds and ZZZ is the number ofmilliseconds.
NAMEfunction::cputime_to_string — Human readable string for given cputime
SYNOPSIS
ARGUMENTS
cputime
Time to translate.
DESCRIPTIONEquivalent to calling: msec_to_string (cputime_to_msecs (cputime).
NAMEfunction::task_time_string — Human readable string of task time usage
SYNOPSIS
ARGUMENTSNone
DESCRIPTIONReturns a human readable string showing the user and system time the current task has used up tonow. For example “usr: 0m12.908s, sys: 1m6.851s”.
NAMEfunction::task_time_string_tid — Human readable string of task time usage
SYNOPSIS
function cputime_to_string:string(cputime:long)
function task_time_string:string()
function task_time_string_tid:string(tid:long)
SystemTap Tapset Reference
80
ARGUMENTS
tid
Thread id of the given task
DESCRIPTIONReturns a human readable string showing the user and system time the given task has used up to now.For example “usr: 0m12.908s, sys: 1m6.851s”.
CHAPTER 7. TASK TIME TAPSET
81
CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSETThis family of probe points is used to probe block IO layer and IO scheduler activities. It contains thefollowing probe points:
NAMEprobe::ioscheduler.elv_next_request — Fires when a request is retrieved from the request queue
SYNOPSIS
VALUES
name
Name of the probe point
elevator_name
The type of I/O elevator currently enabled
NAMEprobe::ioscheduler.elv_next_request.return — Fires when a request retrieval issues a return signal
SYNOPSIS
VALUES
disk_major
Disk major number of the request
rq
Address of the request
name
Name of the probe point
disk_minor
Disk minor number of the request
rq_flags
Request flags
ioscheduler.elv_next_request
ioscheduler.elv_next_request.return
SystemTap Tapset Reference
82
NAMEprobe::ioscheduler.elv_completed_request — Fires when a request is completed
SYNOPSIS
VALUES
disk_major
Disk major number of the request
rq
Address of the request
name
Name of the probe point
elevator_name
The type of I/O elevator currently enabled
disk_minor
Disk minor number of the request
rq_flags
Request flags
NAMEprobe::ioscheduler.elv_add_request.kp — kprobe based probe to indicate that a request was added tothe request queue
SYNOPSIS
VALUES
disk_major
Disk major number of the request
rq
Address of the request
q
pointer to request queue
ioscheduler.elv_completed_request
ioscheduler.elv_add_request.kp
CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSET
83
name
Name of the probe point
elevator_name
The type of I/O elevator currently enabled
disk_minor
Disk minor number of the request
rq_flags
Request flags
NAMEprobe::ioscheduler.elv_add_request.tp — tracepoint based probe to indicate a request is added to therequest queue.
SYNOPSIS
VALUES
disk_major
Disk major no of request.
rq
Address of request.
q
Pointer to request queue.
name
Name of the probe point
elevator_name
The type of I/O elevator currently enabled.
disk_minor
Disk minor number of request.
rq_flags
Request flags.
ioscheduler.elv_add_request.tp
SystemTap Tapset Reference
84
NAMEprobe::ioscheduler.elv_add_request — probe to indicate request is added to the request queue.
SYNOPSIS
VALUES
disk_major
Disk major no of request.
rq
Address of request.
q
Pointer to request queue.
elevator_name
The type of I/O elevator currently enabled.
disk_minor
Disk minor number of request.
rq_flags
Request flags.
NAMEprobe::ioscheduler_trace.elv_completed_request — Fires when a request is
SYNOPSIS
VALUES
disk_major
Disk major no of request.
rq
Address of request.
name
Name of the probe point
ioscheduler.elv_add_request
ioscheduler_trace.elv_completed_request
CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSET
85
elevator_name
The type of I/O elevator currently enabled.
disk_minor
Disk minor number of request.
rq_flags
Request flags.
DESCRIPTIONcompleted.
NAMEprobe::ioscheduler_trace.elv_issue_request — Fires when a request is
SYNOPSIS
VALUES
disk_major
Disk major no of request.
rq
Address of request.
name
Name of the probe point
elevator_name
The type of I/O elevator currently enabled.
disk_minor
Disk minor number of request.
rq_flags
Request flags.
DESCRIPTIONscheduled.
ioscheduler_trace.elv_issue_request
SystemTap Tapset Reference
86
NAMEprobe::ioscheduler_trace.elv_requeue_request — Fires when a request is
SYNOPSIS
VALUES
disk_major
Disk major no of request.
rq
Address of request.
name
Name of the probe point
elevator_name
The type of I/O elevator currently enabled.
disk_minor
Disk minor number of request.
rq_flags
Request flags.
DESCRIPTIONput back on the queue, when the hadware cannot accept more requests.
NAMEprobe::ioscheduler_trace.elv_abort_request — Fires when a request is aborted.
SYNOPSIS
VALUES
disk_major
Disk major no of request.
rq
Address of request.
ioscheduler_trace.elv_requeue_request
ioscheduler_trace.elv_abort_request
CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSET
87
name
Name of the probe point
elevator_name
The type of I/O elevator currently enabled.
disk_minor
Disk minor number of request.
rq_flags
Request flags.
NAMEprobe::ioscheduler_trace.plug — Fires when a request queue is plugged;
SYNOPSIS
VALUES
name
Name of the probe point
rq_queue
request queue
DESCRIPTIONie, requests in the queue cannot be serviced by block driver.
NAMEprobe::ioscheduler_trace.unplug_io — Fires when a request queue is unplugged;
SYNOPSIS
VALUES
name
Name of the probe point
rq_queue
ioscheduler_trace.plug
ioscheduler_trace.unplug_io
SystemTap Tapset Reference
88
request queue
DESCRIPTIONEither, when number of pending requests in the queue exceeds threshold or, upon expiration of timerthat was activated when queue was plugged.
NAMEprobe::ioscheduler_trace.unplug_timer — Fires when unplug timer associated
SYNOPSIS
VALUES
name
Name of the probe point
rq_queue
request queue
DESCRIPTIONwith a request queue expires.
NAMEprobe::ioblock.request — Fires whenever making a generic block I/O request.
SYNOPSIS
VALUESNone
DESCRIPTIONname - name of the probe point devname - block device name ino - i-node number of the mapped file sector - beginning sector for the entire bio flags - see below BIO_UPTODATE 0 ok after I/Ocompletion BIO_RW_BLOCK 1 RW_AHEAD set, and read/write would block BIO_EOF 2 out-out-boundserror BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4 doesn't own data BIO_BOUNCED 5 bio is abounce bio BIO_USER_MAPPED 6 contains user pages BIO_EOPNOTSUPP 7 not supported
rw - binary trace for read/write request vcnt - bio vector count which represents number of arrayelement (page, offset, length) which make up this I/O request idx - offset into the bio vector array phys_segments - number of segments in this bio after physical address coalescing is performed hw_segments - number of segments after physical and DMA remapping hardware coalescing is
ioscheduler_trace.unplug_timer
ioblock.request
CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSET
89
performed size - total size in bytes bdev - target block device bdev_contains - points to the deviceobject which contains the partition (when bio structure represents a partition) p_start_sect - pointsto the start sector of the partition structure of the device
CONTEXTThe process makes block I/O request
NAMEprobe::ioblock.end — Fires whenever a block I/O transfer is complete.
SYNOPSIS
VALUESNone
DESCRIPTIONname - name of the probe point devname - block device name ino - i-node number of the mapped file bytes_done - number of bytes transferred sector - beginning sector for the entire bio flags - seebelow BIO_UPTODATE 0 ok after I/O completion BIO_RW_BLOCK 1 RW_AHEAD set, and read/writewould block BIO_EOF 2 out-out-bounds error BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4doesn't own data BIO_BOUNCED 5 bio is a bounce bio BIO_USER_MAPPED 6 contains user pagesBIO_EOPNOTSUPP 7 not supported error - 0 on success rw - binary trace for read/write request vcnt - bio vector count which represents number of array element (page, offset, length) which makesup this I/O request idx - offset into the bio vector array phys_segments - number of segments inthis bio after physical address coalescing is performed. hw_segments - number of segments afterphysical and DMA remapping hardware coalescing is performed size - total size in bytes
CONTEXTThe process signals the transfer is done.
NAMEprobe::ioblock_trace.bounce — Fires whenever a buffer bounce is needed for at least one page of ablock IO request.
SYNOPSIS
VALUESNone
DESCRIPTIONname - name of the probe point q - request queue on which this bio was queued. devname - device forwhich a buffer bounce was needed. ino - i-node number of the mapped file bytes_done - number ofbytes transferred sector - beginning sector for the entire bio flags - see below BIO_UPTODATE 0
ioblock.end
ioblock_trace.bounce
SystemTap Tapset Reference
90
ok after I/O completion BIO_RW_BLOCK 1 RW_AHEAD set, and read/write would block BIO_EOF 2 out-out-bounds error BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4 doesn't own data BIO_BOUNCED5 bio is a bounce bio BIO_USER_MAPPED 6 contains user pages BIO_EOPNOTSUPP 7 not supported rw - binary trace for read/write request vcnt - bio vector count which represents number of arrayelement (page, offset, length) which makes up this I/O request idx - offset into the bio vector array phys_segments - number of segments in this bio after physical address coalescing is performed. size - total size in bytes bdev - target block device bdev_contains - points to the device objectwhich contains the partition (when bio structure represents a partition) p_start_sect - points to thestart sector of the partition structure of the device
CONTEXTThe process creating a block IO request.
NAMEprobe::ioblock_trace.request — Fires just as a generic block I/O request is created for a bio.
SYNOPSIS
VALUESNone
DESCRIPTIONname - name of the probe point q - request queue on which this bio was queued. devname - blockdevice name ino - i-node number of the mapped file bytes_done - number of bytes transferred sector - beginning sector for the entire bio flags - see below BIO_UPTODATE 0 ok after I/Ocompletion BIO_RW_BLOCK 1 RW_AHEAD set, and read/write would block BIO_EOF 2 out-out-boundserror BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4 doesn't own data BIO_BOUNCED 5 bio is abounce bio BIO_USER_MAPPED 6 contains user pages BIO_EOPNOTSUPP 7 not supported
rw - binary trace for read/write request vcnt - bio vector count which represents number of arrayelement (page, offset, length) which make up this I/O request idx - offset into the bio vector array phys_segments - number of segments in this bio after physical address coalescing is performed. size - total size in bytes bdev - target block device bdev_contains - points to the device objectwhich contains the partition (when bio structure represents a partition) p_start_sect - points to thestart sector of the partition structure of the device
CONTEXTThe process makes block I/O request
NAMEprobe::ioblock_trace.end — Fires whenever a block I/O transfer is complete.
SYNOPSIS
ioblock_trace.request
ioblock_trace.end
CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSET
91
VALUESNone
DESCRIPTIONname - name of the probe point q - request queue on which this bio was queued. devname - blockdevice name ino - i-node number of the mapped file bytes_done - number of bytes transferred sector - beginning sector for the entire bio flags - see below BIO_UPTODATE 0 ok after I/Ocompletion BIO_RW_BLOCK 1 RW_AHEAD set, and read/write would block BIO_EOF 2 out-out-boundserror BIO_SEG_VALID 3 nr_hw_seg valid BIO_CLONED 4 doesn't own data BIO_BOUNCED 5 bio is abounce bio BIO_USER_MAPPED 6 contains user pages BIO_EOPNOTSUPP 7 not supported
rw - binary trace for read/write request vcnt - bio vector count which represents number of arrayelement (page, offset, length) which makes up this I/O request idx - offset into the bio vector array phys_segments - number of segments in this bio after physical address coalescing is performed. size - total size in bytes bdev - target block device bdev_contains - points to the device objectwhich contains the partition (when bio structure represents a partition) p_start_sect - points to thestart sector of the partition structure of the device
CONTEXTThe process signals the transfer is done.
SystemTap Tapset Reference
92
CHAPTER 9. SCSI TAPSETThis family of probe points is used to probe SCSI activities. It contains the following probe points:
NAMEprobe::scsi.ioentry — Prepares a SCSI mid-layer request
SYNOPSIS
VALUES
disk_major
The major number of the disk (-1 if no information)
device_state_str
The current state of the device, as a string
device_state
The current state of the device
req_addr
The current struct request pointer, as a number
disk_minor
The minor number of the disk (-1 if no information)
NAMEprobe::scsi.iodispatching — SCSI mid-layer dispatched low-level SCSI command
SYNOPSIS
VALUES
device_state_str
The current state of the device, as a string
dev_id
The scsi device id
channel
scsi.ioentry
scsi.iodispatching
CHAPTER 9. SCSI TAPSET
93
The channel number
data_direction
The data_direction specifies whether this command is from/to the device 0(DMA_BIDIRECTIONAL), 1 (DMA_TO_DEVICE), 2 (DMA_FROM_DEVICE), 3 (DMA_NONE)
lun
The lun number
request_bufflen
The request buffer length
host_no
The host number
device_state
The current state of the device
data_direction_str
Data direction, as a string
req_addr
The current struct request pointer, as a number
request_buffer
The request buffer address
NAMEprobe::scsi.iodone — SCSI command completed by low level driver and enqueued into the done queue.
SYNOPSIS
VALUES
device_state_str
The current state of the device, as a string
dev_id
The scsi device id
channel
The channel number
scsi.iodone
SystemTap Tapset Reference
94
data_direction
The data_direction specifies whether this command is from/to the device.
lun
The lun number
host_no
The host number
data_direction_str
Data direction, as a string
device_state
The current state of the device
scsi_timer_pending
1 if a timer is pending on this request
req_addr
The current struct request pointer, as a number
NAMEprobe::scsi.iocompleted — SCSI mid-layer running the completion processing for block device I/Orequests
SYNOPSIS
VALUES
device_state_str
The current state of the device, as a string
dev_id
The scsi device id
channel
The channel number
data_direction
The data_direction specifies whether this command is from/to the device
lun
scsi.iocompleted
CHAPTER 9. SCSI TAPSET
95
The lun number
host_no
The host number
data_direction_str
Data direction, as a string
device_state
The current state of the device
req_addr
The current struct request pointer, as a number
goodbytes
The bytes completed
NAMEprobe::scsi.ioexecute — Create mid-layer SCSI request and wait for the result
SYNOPSIS
VALUES
retries
Number of times to retry request
device_state_str
The current state of the device, as a string
dev_id
The scsi device id
channel
The channel number
data_direction
The data_direction specifies whether this command is from/to the device.
lun
The lun number
scsi.ioexecute
SystemTap Tapset Reference
96
timeout
Request timeout in seconds
request_bufflen
The data buffer buffer length
host_no
The host number
data_direction_str
Data direction, as a string
device_state
The current state of the device
request_buffer
The data buffer address
NAMEprobe::scsi.set_state — Order SCSI device state change
SYNOPSIS
VALUES
state_str
The new state of the device, as a string
dev_id
The scsi device id
channel
The channel number
state
The new state of the device
old_state_str
The current state of the device, as a string
lun
The lun number
scsi.set_state
CHAPTER 9. SCSI TAPSET
97
old_state
The current state of the device
host_no
The host number
SystemTap Tapset Reference
98
CHAPTER 10. TTY TAPSETThis family of probe points is used to probe TTY (Teletype) activities. It contains the following probepoints:
NAMEprobe::tty.open — Called when a tty is opened
SYNOPSIS
VALUES
inode_state
the inode state
file_name
the file name
file_mode
the file mode
file_flags
the file flags
inode_number
the inode number
inode_flags
the inode flags
NAMEprobe::tty.release — Called when the tty is closed
SYNOPSIS
VALUES
inode_state
the inode state
tty.open
tty.release
CHAPTER 10. TTY TAPSET
99
file_name
the file name
file_mode
the file mode
file_flags
the file flags
inode_number
the inode number
inode_flags
the inode flags
NAMEprobe::tty.resize — Called when a terminal resize happens
SYNOPSIS
VALUES
new_ypixel
the new ypixel value
old_col
the old col value
old_xpixel
the old xpixel
old_ypixel
the old ypixel
name
the tty name
old_row
the old row value
new_row
the new row value
tty.resize
SystemTap Tapset Reference
100
new_xpixel
the new xpixel value
new_col
the new col value
NAMEprobe::tty.ioctl — called when a ioctl is request to the tty
SYNOPSIS
VALUES
cmd
the ioctl command
arg
the ioctl argument
name
the file name
NAMEprobe::tty.init — Called when a tty is being initalized
SYNOPSIS
VALUES
driver_name
the driver name
name
the driver .dev_name name
module
the module name
tty.ioctl
tty.init
CHAPTER 10. TTY TAPSET
101
NAMEprobe::tty.register — Called when a tty device is registred
SYNOPSIS
VALUES
driver_name
the driver name
name
the driver .dev_name name
index
the tty index requested
module
the module name
NAMEprobe::tty.unregister — Called when a tty device is being unregistered
SYNOPSIS
VALUES
driver_name
the driver name
name
the driver .dev_name name
index
the tty index requested
module
the module name
tty.register
tty.unregister
SystemTap Tapset Reference
102
NAMEprobe::tty.poll — Called when a tty device is being polled
SYNOPSIS
VALUES
file_name
the tty file name
wait_key
the wait queue key
NAMEprobe::tty.receive — called when a tty receives a message
SYNOPSIS
VALUES
driver_name
the driver name
count
The amount of characters received
name
the name of the module file
fp
The flag buffer
cp
the buffer that was received
index
The tty Index
id
the tty id
tty.poll
tty.receive
CHAPTER 10. TTY TAPSET
103
NAMEprobe::tty.write — write to the tty line
SYNOPSIS
VALUES
driver_name
the driver name
buffer
the buffer that will be written
file_name
the file name lreated to the tty
nr
The amount of characters
NAMEprobe::tty.read — called when a tty line will be read
SYNOPSIS
VALUES
driver_name
the driver name
buffer
the buffer that will receive the characters
file_name
the file name lreated to the tty
nr
The amount of characters to be read
tty.write
tty.read
SystemTap Tapset Reference
104
CHAPTER 11. NETWORKING TAPSETThis family of probe points is used to probe the activities of the network device and protocol layers.
NAMEprobe::netdev.receive — Data received from network device.
SYNOPSIS
VALUES
protocol
Protocol of received packet.
dev_name
The name of the device. e.g: eth0, ath1.
length
The length of the receiving buffer.
NAMEprobe::netdev.transmit — Network device transmitting buffer
SYNOPSIS
VALUES
protocol
The protocol of this packet(defined in include/linux/if_ether.h).
dev_name
The name of the device. e.g: eth0, ath1.
length
The length of the transmit buffer.
truesize
The size of the data to be transmitted.
netdev.receive
netdev.transmit
CHAPTER 11. NETWORKING TAPSET
105
NAMEprobe::netdev.change_mtu — Called when the netdev MTU is changed
SYNOPSIS
VALUES
dev_name
The device that will have the MTU changed
new_mtu
The new MTU
old_mtu
The current MTU
NAMEprobe::netdev.open — Called when the device is opened
SYNOPSIS
VALUES
dev_name
The device that is going to be opened
NAMEprobe::netdev.close — Called when the device is closed
SYNOPSIS
VALUES
dev_name
The device that is going to be closed
netdev.change_mtu
netdev.open
netdev.close
SystemTap Tapset Reference
106
NAMEprobe::netdev.hard_transmit — Called when the devices is going to TX (hard)
SYNOPSIS
VALUES
protocol
The protocol used in the transmission
dev_name
The device scheduled to transmit
length
The length of the transmit buffer.
truesize
The size of the data to be transmitted.
NAMEprobe::netdev.rx — Called when the device is going to receive a packet
SYNOPSIS
VALUES
protocol
The packet protocol
dev_name
The device received the packet
NAMEprobe::netdev.change_rx_flag — Called when the device RX flag will be changed
SYNOPSIS
netdev.hard_transmit
netdev.rx
netdev.change_rx_flag
CHAPTER 11. NETWORKING TAPSET
107
VALUES
dev_name
The device that will be changed
flags
The new flags
NAMEprobe::netdev.set_promiscuity — Called when the device enters/leaves promiscuity
SYNOPSIS
VALUES
dev_name
The device that is entering/leaving promiscuity mode
enable
If the device is entering promiscuity mode
inc
Count the number of promiscuity openers
disable
If the device is leaving promiscuity mode
NAMEprobe::netdev.ioctl — Called when the device suffers an IOCTL
SYNOPSIS
VALUES
cmd
The IOCTL request
arg
netdev.set_promiscuity
netdev.ioctl
SystemTap Tapset Reference
108
The IOCTL argument (usually the netdev interface)
NAMEprobe::netdev.register — Called when the device is registered
SYNOPSIS
VALUES
dev_name
The device that is going to be registered
NAMEprobe::netdev.unregister — Called when the device is being unregistered
SYNOPSIS
VALUES
dev_name
The device that is going to be unregistered
NAMEprobe::netdev.get_stats — Called when someone asks the device statistics
SYNOPSIS
VALUES
dev_name
The device that is going to provide the statistics
netdev.register
netdev.unregister
netdev.get_stats
CHAPTER 11. NETWORKING TAPSET
109
NAMEprobe::netdev.change_mac — Called when the netdev_name has the MAC changed
SYNOPSIS
VALUES
dev_name
The device that will have the MTU changed
new_mac
The new MAC address
mac_len
The MAC length
old_mac
The current MAC address
NAMEprobe::tcp.sendmsg — Sending a tcp message
SYNOPSIS
VALUES
name
Name of this probe
size
Number of bytes to send
sock
Network socket
CONTEXTThe process which sends a tcp message
netdev.change_mac
tcp.sendmsg
SystemTap Tapset Reference
110
NAMEprobe::tcp.sendmsg.return — Sending TCP message is done
SYNOPSIS
VALUES
name
Name of this probe
size
Number of bytes sent or error code if an error occurred.
CONTEXTThe process which sends a tcp message
NAMEprobe::tcp.recvmsg — Receiving TCP message
SYNOPSIS
VALUES
saddr
A string representing the source IP address
daddr
A string representing the destination IP address
name
Name of this probe
sport
TCP source port
dport
TCP destination port
size
Number of bytes to be received
tcp.sendmsg.return
tcp.recvmsg
CHAPTER 11. NETWORKING TAPSET
111
sock
Network socket
CONTEXTThe process which receives a tcp message
NAMEprobe::tcp.recvmsg.return — Receiving TCP message complete
SYNOPSIS
VALUES
saddr
A string representing the source IP address
daddr
A string representing the destination IP address
name
Name of this probe
sport
TCP source port
dport
TCP destination port
size
Number of bytes received or error code if an error occurred.
CONTEXTThe process which receives a tcp message
NAMEprobe::tcp.disconnect — TCP socket disconnection
SYNOPSIS
tcp.recvmsg.return
tcp.disconnect
SystemTap Tapset Reference
112
VALUES
saddr
A string representing the source IP address
daddr
A string representing the destination IP address
flags
TCP flags (e.g. FIN, etc)
name
Name of this probe
sport
TCP source port
dport
TCP destination port
sock
Network socket
CONTEXTThe process which disconnects tcp
NAMEprobe::tcp.disconnect.return — TCP socket disconnection complete
SYNOPSIS
VALUES
ret
Error code (0: no error)
name
Name of this probe
CONTEXTThe process which disconnects tcp
tcp.disconnect.return
CHAPTER 11. NETWORKING TAPSET
113
NAMEprobe::tcp.setsockopt — Call to setsockopt
SYNOPSIS
VALUES
optstr
Resolves optname to a human-readable format
level
The level at which the socket options will be manipulated
optlen
Used to access values for setsockopt
name
Name of this probe
optname
TCP socket options (e.g. TCP_NODELAY, TCP_MAXSEG, etc)
sock
Network socket
CONTEXTThe process which calls setsockopt
NAMEprobe::tcp.setsockopt.return — Return from setsockopt
SYNOPSIS
VALUES
ret
Error code (0: no error)
name
Name of this probe
tcp.setsockopt
tcp.setsockopt.return
SystemTap Tapset Reference
114
CONTEXTThe process which calls setsockopt
NAMEprobe::tcp.receive — Called when a TCP packet is received
SYNOPSIS
VALUES
urg
TCP URG flag
protocol
Packet protocol from driver
psh
TCP PSH flag
name
Name of the probe point
rst
TCP RST flag
dport
TCP destination port
saddr
A string representing the source IP address
daddr
A string representing the destination IP address
ack
TCP ACK flag
fin
TCP FIN flag
syn
TCP SYN flag
tcp.receive
CHAPTER 11. NETWORKING TAPSET
115
sport
TCP source port
iphdr
IP header address
NAMEprobe::udp.sendmsg — Fires whenever a process sends a UDP message
SYNOPSIS
VALUES
name
The name of this probe
size
Number of bytes sent by the process
sock
Network socket used by the process
CONTEXTThe process which sent a UDP message
NAMEprobe::udp.sendmsg.return — Fires whenever an attempt to send a UDP message is completed
SYNOPSIS
VALUES
name
The name of this probe
size
Number of bytes sent by the process
udp.sendmsg
udp.sendmsg.return
SystemTap Tapset Reference
116
CONTEXTThe process which sent a UDP message
NAMEprobe::udp.recvmsg — Fires whenever a UDP message is received
SYNOPSIS
VALUES
name
The name of this probe
size
Number of bytes received by the process
sock
Network socket used by the process
CONTEXTThe process which received a UDP message
NAMEprobe::udp.recvmsg.return — Fires whenever an attempt to receive a UDP message received iscompleted
SYNOPSIS
VALUES
name
The name of this probe
size
Number of bytes received by the process
CONTEXTThe process which received a UDP message
udp.recvmsg
udp.recvmsg.return
CHAPTER 11. NETWORKING TAPSET
117
NAMEprobe::udp.disconnect — Fires when a process requests for a UDP disconnection
SYNOPSIS
VALUES
flags
Flags (e.g. FIN, etc)
name
The name of this probe
sock
Network socket used by the process
CONTEXTThe process which requests a UDP disconnection
NAMEprobe::udp.disconnect.return — UDP has been disconnected successfully
SYNOPSIS
VALUES
ret
Error code (0: no error)
name
The name of this probe
CONTEXTThe process which requested a UDP disconnection
NAMEfunction::ip_ntop — returns a string representation from an integer IP number
SYNOPSIS
udp.disconnect
udp.disconnect.return
SystemTap Tapset Reference
118
ARGUMENTS
addr
the ip represented as an integer
function ip_ntop:string(addr:long)
CHAPTER 11. NETWORKING TAPSET
119
CHAPTER 12. SOCKET TAPSETThis family of probe points is used to probe socket activities. It contains the following probe points:
NAMEprobe::socket.send — Message sent on a socket.
SYNOPSIS
VALUES
success
Was send successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Size of message sent (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
CONTEXTThe message sender
NAMEprobe::socket.receive — Message received on a socket.
SYNOPSIS
socket.send
SystemTap Tapset Reference
120
VALUES
success
Was send successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Size of message received (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
CONTEXTThe message receiver
NAMEprobe::socket.sendmsg — Message is currently being sent on a socket.
SYNOPSIS
VALUES
protocol
Protocol value
flags
socket.receive
socket.sendmsg
CHAPTER 12. SOCKET TAPSET
121
Socket flags value
name
Name of this probe
state
Socket state value
size
Message size in bytes
type
Socket type value
family
Protocol family value
CONTEXTThe message sender
DESCRIPTIONFires at the beginning of sending a message on a socket via the sock_sendmsg function
NAMEprobe::socket.sendmsg.return — Return from socket.sendmsg.
SYNOPSIS
VALUES
success
Was send successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
socket.sendmsg.return
SystemTap Tapset Reference
122
Socket state value
size
Size of message sent (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
CONTEXTThe message sender.
DESCRIPTIONFires at the conclusion of sending a message on a socket via the sock_sendmsg function
NAMEprobe::socket.recvmsg — Message being received on socket
SYNOPSIS
VALUES
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Message size in bytes
type
Socket type value
family
socket.recvmsg
CHAPTER 12. SOCKET TAPSET
123
Protocol family value
CONTEXTThe message receiver.
DESCRIPTIONFires at the beginning of receiving a message on a socket via the sock_recvmsg function
NAMEprobe::socket.recvmsg.return — Return from Message being received on socket
SYNOPSIS
VALUES
success
Was receive successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Size of message received (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
CONTEXTThe message receiver.
socket.recvmsg.return
SystemTap Tapset Reference
124
DESCRIPTIONFires at the conclusion of receiving a message on a socket via the sock_recvmsg function.
NAMEprobe::socket.aio_write — Message send via sock_aio_write
SYNOPSIS
VALUES
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Message size in bytes
type
Socket type value
family
Protocol family value
CONTEXTThe message sender
DESCRIPTIONFires at the beginning of sending a message on a socket via the sock_aio_write function
NAMEprobe::socket.aio_write.return — Conclusion of message send via sock_aio_write
SYNOPSIS
socket.aio_write
CHAPTER 12. SOCKET TAPSET
125
VALUES
success
Was receive successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Size of message received (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
CONTEXTThe message receiver.
DESCRIPTIONFires at the conclusion of sending a message on a socket via the sock_aio_write function
NAMEprobe::socket.aio_read — Receiving message via sock_aio_read
SYNOPSIS
VALUES
protocol
socket.aio_write.return
socket.aio_read
SystemTap Tapset Reference
126
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Message size in bytes
type
Socket type value
family
Protocol family value
CONTEXTThe message sender
DESCRIPTIONFires at the beginning of receiving a message on a socket via the sock_aio_read function
NAMEprobe::socket.aio_read.return — Conclusion of message received via sock_aio_read
SYNOPSIS
VALUES
success
Was receive successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
socket.aio_read.return
CHAPTER 12. SOCKET TAPSET
127
Name of this probe
state
Socket state value
size
Size of message received (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
CONTEXTThe message receiver.
DESCRIPTIONFires at the conclusion of receiving a message on a socket via the sock_aio_read function
NAMEprobe::socket.writev — Message sent via socket_writev
SYNOPSIS
VALUES
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Message size in bytes
type
socket.writev
SystemTap Tapset Reference
128
Socket type value
family
Protocol family value
CONTEXTThe message sender
DESCRIPTIONFires at the beginning of sending a message on a socket via the sock_writev function
NAMEprobe::socket.writev.return — Conclusion of message sent via socket_writev
SYNOPSIS
VALUES
success
Was send successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Size of message sent (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
socket.writev.return
CHAPTER 12. SOCKET TAPSET
129
CONTEXTThe message receiver.
DESCRIPTIONFires at the conclusion of sending a message on a socket via the sock_writev function
NAMEprobe::socket.readv — Receiving a message via sock_readv
SYNOPSIS
VALUES
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Message size in bytes
type
Socket type value
family
Protocol family value
CONTEXTThe message sender
DESCRIPTIONFires at the beginning of receiving a message on a socket via the sock_readv function
NAME
socket.readv
SystemTap Tapset Reference
130
probe::socket.readv.return — Conclusion of receiving a message via sock_readv
SYNOPSIS
VALUES
success
Was receive successful? (1 = yes, 0 = no)
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
size
Size of message received (in bytes) or error code if success = 0
type
Socket type value
family
Protocol family value
CONTEXTThe message receiver.
DESCRIPTIONFires at the conclusion of receiving a message on a socket via the sock_readv function
NAMEprobe::socket.create — Creation of a socket
SYNOPSIS
socket.readv.return
socket.create
CHAPTER 12. SOCKET TAPSET
131
VALUES
protocol
Protocol value
name
Name of this probe
requester
Requested by user process or the kernel (1 = kernel, 0 = user)
type
Socket type value
family
Protocol family value
CONTEXTThe requester (see requester variable)
DESCRIPTIONFires at the beginning of creating a socket.
NAMEprobe::socket.create.return — Return from Creation of a socket
SYNOPSIS
VALUES
success
Was socket creation successful? (1 = yes, 0 = no)
protocol
Protocol value
err
Error code if success == 0
name
Name of this probe
requester
socket.create.return
SystemTap Tapset Reference
132
Requested by user process or the kernel (1 = kernel, 0 = user)
type
Socket type value
family
Protocol family value
CONTEXTThe requester (user process or kernel)
DESCRIPTIONFires at the conclusion of creating a socket.
NAMEprobe::socket.close — Close a socket
SYNOPSIS
VALUES
protocol
Protocol value
flags
Socket flags value
name
Name of this probe
state
Socket state value
type
Socket type value
family
Protocol family value
CONTEXTThe requester (user process or kernel)
socket.close
CHAPTER 12. SOCKET TAPSET
133
DESCRIPTIONFires at the beginning of closing a socket.
NAMEprobe::socket.close.return — Return from closing a socket
SYNOPSIS
VALUES
name
Name of this probe
CONTEXTThe requester (user process or kernel)
DESCRIPTIONFires at the conclusion of closing a socket.
NAMEfunction::sock_prot_num2str — Given a protocol number, return a string representation.
SYNOPSIS
ARGUMENTS
proto
The protocol number.
NAMEfunction::sock_prot_str2num — Given a protocol name (string), return the corresponding protocolnumber.
SYNOPSIS
ARGUMENTS
socket.close.return
function sock_prot_num2str:string(proto:long)
function sock_prot_str2num:long(proto:string)
SystemTap Tapset Reference
134
proto
The protocol name.
NAMEfunction::sock_fam_num2str — Given a protocol family number, return a string representation.
SYNOPSIS
ARGUMENTS
family
The family number.
NAMEfunction::sock_fam_str2num — Given a protocol family name (string), return the corresponding
SYNOPSIS
ARGUMENTS
family
The family name.
DESCRIPTIONprotocol family number.
NAMEfunction::sock_state_num2str — Given a socket state number, return a string representation.
SYNOPSIS
ARGUMENTS
state
The state number.
function sock_fam_num2str:string(family:long)
function sock_fam_str2num:long(family:string)
function sock_state_num2str:string(state:long)
CHAPTER 12. SOCKET TAPSET
135
NAMEfunction::sock_state_str2num — Given a socket state string, return the corresponding state number.
SYNOPSIS
ARGUMENTS
state
The state name.
function sock_state_str2num:long(state:string)
SystemTap Tapset Reference
136
CHAPTER 13. KERNEL PROCESS TAPSETThis family of probe points is used to probe process-related activities. It contains the following probepoints:
NAMEprobe::kprocess.create — Fires whenever a new process is successfully created
SYNOPSIS
VALUES
new_pid
The PID of the newly created process
CONTEXTParent of the created process.
DESCRIPTIONFires whenever a new process is successfully created, either as a result of fork (or one of its syscallvariants), or a new kernel thread.
NAMEprobe::kprocess.start — Starting new process
SYNOPSIS
VALUESNone
CONTEXTNewly created process.
DESCRIPTIONFires immediately before a new process begins execution.
NAMEprobe::kprocess.exec — Attempt to exec to a new program
SYNOPSIS
kprocess.create
kprocess.start
CHAPTER 13. KERNEL PROCESS TAPSET
137
VALUES
filename
The path to the new executable
CONTEXTThe caller of exec.
DESCRIPTIONFires whenever a process attempts to exec to a new program.
NAMEprobe::kprocess.exec_complete — Return from exec to a new program
SYNOPSIS
VALUES
success
A boolean indicating whether the exec was successful
errno
The error number resulting from the exec
CONTEXTOn success, the context of the new executable. On failure, remains in the context of the caller.
DESCRIPTIONFires at the completion of an exec call.
NAMEprobe::kprocess.exit — Exit from process
SYNOPSIS
VALUES
code
kprocess.exec
kprocess.exec_complete
kprocess.exit
SystemTap Tapset Reference
138
The exit code of the process
CONTEXTThe process which is terminating.
DESCRIPTIONFires when a process terminates. This will always be followed by a kprocess.release, though the lattermay be delayed if the process waits in a zombie state.
NAMEprobe::kprocess.release — Process released
SYNOPSIS
VALUES
pid
PID of the process being released
task
A task handle to the process being released
CONTEXTThe context of the parent, if it wanted notification of this process' termination, else the context of theprocess itself.
DESCRIPTIONFires when a process is released from the kernel. This always follows a kprocess.exit, though it may bedelayed somewhat if the process waits in a zombie state.
kprocess.release
CHAPTER 13. KERNEL PROCESS TAPSET
139
CHAPTER 14. SIGNAL TAPSETThis family of probe points is used to probe signal activities. It contains the following probe points:
NAMEprobe::signal.send — Signal being sent to a process
SYNOPSIS
VALUES
send2queue
Indicates whether the signal is sent to an existing sigqueue
name
The name of the function used to send out the signal
task
A task handle to the signal recipient
sinfo
The address of siginfo struct
si_code
Indicates the signal type
sig_name
A string representation of the signal
sig
The number of the signal
shared
Indicates whether the signal is shared by the thread group
sig_pid
The PID of the process receiving the signal
pid_name
The name of the signal recipient
CONTEXTThe signal's sender.
signal.send
SystemTap Tapset Reference
140
NAMEprobe::signal.send.return — Signal being sent to a process completed
SYNOPSIS
VALUES
retstr
The return value to either __group_send_sig_info, specific_send_sig_info, or send_sigqueue
send2queue
Indicates whether the sent signal was sent to an existing sigqueue
name
The name of the function used to send out the signal
shared
Indicates whether the sent signal is shared by the thread group.
CONTEXTThe signal's sender. (correct?)
DESCRIPTIONPossible __group_send_sig_info and specific_send_sig_info return values are as follows;
0 -- The signal is sucessfully sent to a process,
WHICH MEANS THAT(1) the signal was ignored by the receiving process, (2) this is a non-RT signal and the system alreadyhas one queued, and (3) the signal was successfully added to the sigqueue of the receiving process.
-EAGAIN -- The sigqueue of the receiving process is overflowing, the signal was RT, and the signal wassent by a user using something other than kill.
Possible send_group_sigqueue and send_sigqueue return values are as follows;
0 -- The signal was either sucessfully added into the sigqueue of the receiving process, or a SI_TIMERentry is already queued (in which case, the overrun count will be simply incremented).
1 -- The signal was ignored by the receiving process.
-1 -- (send_sigqueue only) The task was marked exiting, allowing * posix_timer_event to redirect it tothe group leader.
signal.send.return
CHAPTER 14. SIGNAL TAPSET
141
NAMEprobe::signal.checkperm — Check being performed on a sent signal
SYNOPSIS
VALUES
name
Name of the probe point
task
A task handle to the signal recipient
sinfo
The address of the siginfo structure
si_code
Indicates the signal type
sig_name
A string representation of the signal
sig
The number of the signal
pid_name
Name of the process receiving the signal
sig_pid
The PID of the process receiving the signal
NAMEprobe::signal.checkperm.return — Check performed on a sent signal completed
SYNOPSIS
VALUES
retstr
Return value as a string
signal.checkperm
signal.checkperm.return
SystemTap Tapset Reference
142
name
Name of the probe point
NAMEprobe::signal.wakeup — Sleeping process being wakened for signal
SYNOPSIS
VALUES
resume
Indicates whether to wake up a task in a STOPPED or TRACED state
state_mask
A string representation indicating the mask of task states to wake. Possible values areTASK_INTERRUPTIBLE, TASK_STOPPED, TASK_TRACED, and TASK_INTERRUPTIBLE.
pid_name
Name of the process to wake
sig_pid
The PID of the process to wake
NAMEprobe::signal.check_ignored — Checking to see signal is ignored
SYNOPSIS
VALUES
sig_name
A string representation of the signal
sig
The number of the signal
pid_name
Name of the process receiving the signal
signal.wakeup
signal.check_ignored
CHAPTER 14. SIGNAL TAPSET
143
sig_pid
The PID of the process receiving the signal
NAMEprobe::signal.check_ignored.return — Check to see signal is ignored completed
SYNOPSIS
VALUES
retstr
Return value as a string
name
Name of the probe point
NAMEprobe::signal.force_segv — Forcing send of SIGSEGV
SYNOPSIS
VALUES
name
Name of the probe point
sig_name
A string representation of the signal
sig
The number of the signal
pid_name
Name of the process receiving the signal
sig_pid
The PID of the process receiving the signal
signal.check_ignored.return
signal.force_segv
SystemTap Tapset Reference
144
NAMEprobe::signal.force_segv.return — Forcing send of SIGSEGV complete
SYNOPSIS
VALUES
retstr
Return value as a string
name
Name of the probe point
NAMEprobe::signal.syskill — Sending kill signal to a process
SYNOPSIS
VALUES
name
Name of the probe point
sig_name
A string representation of the signal
sig
The specific signal sent to the process
pid_name
The name of the signal recipient
sig_pid
The PID of the process receiving the signal
NAMEprobe::signal.syskill.return — Sending kill signal completed
signal.force_segv.return
signal.syskill
CHAPTER 14. SIGNAL TAPSET
145
SYNOPSIS
VALUESNone
NAMEprobe::signal.sys_tkill — Sending a kill signal to a thread
SYNOPSIS
VALUES
name
Name of the probe point
sig_name
A string representation of the signal
sig
The specific signal sent to the process
pid_name
The name of the signal recipient
sig_pid
The PID of the process receiving the kill signal
DESCRIPTIONThe tkill call is analogous to kill(2), except that it also allows a process within a specific thread group tobe targeted. Such processes are targeted through their unique thread IDs (TID).
NAMEprobe::signal.systkill.return — Sending kill signal to a thread completed
SYNOPSIS
VALUES
signal.syskill.return
signal.sys_tkill
signal.systkill.return
SystemTap Tapset Reference
146
retstr
The return value to either __group_send_sig_info,
name
Name of the probe point
NAMEprobe::signal.sys_tgkill — Sending kill signal to a thread group
SYNOPSIS
VALUES
name
Name of the probe point
sig_name
A string representation of the signal
sig
The specific kill signal sent to the process
tgid
The thread group ID of the thread receiving the kill signal
pid_name
The name of the signal recipient
sig_pid
The PID of the thread receiving the kill signal
DESCRIPTIONThe tgkill call is similar to tkill, except that it also allows the caller to specify the thread group ID of thethread to be signalled. This protects against TID reuse.
NAMEprobe::signal.sys_tgkill.return — Sending kill signal to a thread group completed
SYNOPSIS
signal.sys_tgkill
CHAPTER 14. SIGNAL TAPSET
147
VALUES
retstr
The return value to either __group_send_sig_info,
name
Name of the probe point
NAMEprobe::signal.send_sig_queue — Queuing a signal to a process
SYNOPSIS
VALUES
sigqueue_addr
The address of the signal queue
name
Name of the probe point
sig_name
A string representation of the signal
sig
The queued signal
pid_name
Name of the process to which the signal is queued
sig_pid
The PID of the process to which the signal is queued
NAMEprobe::signal.send_sig_queue.return — Queuing a signal to a process completed
SYNOPSIS
signal.sys_tgkill.return
signal.send_sig_queue
SystemTap Tapset Reference
148
VALUES
retstr
Return value as a string
name
Name of the probe point
NAMEprobe::signal.pending — Examining pending signal
SYNOPSIS
VALUES
name
Name of the probe point
sigset_size
The size of the user-space signal set
sigset_add
The address of the user-space signal set (sigset_t)
DESCRIPTIONThis probe is used to examine a set of signals pending for delivery to a specific thread. This normallyoccurs when the do_sigpending kernel function is executed.
NAMEprobe::signal.pending.return — Examination of pending signal completed
SYNOPSIS
VALUES
retstr
Return value as a string
signal.send_sig_queue.return
signal.pending
signal.pending.return
CHAPTER 14. SIGNAL TAPSET
149
name
Name of the probe point
NAMEprobe::signal.handle — Signal handler being invoked
SYNOPSIS
VALUES
regs
The address of the kernel-mode stack area
sig_code
The si_code value of the siginfo signal
name
Name of the probe point
sig_mode
Indicates whether the signal was a user-mode or kernel-mode signal
sinfo
The address of the siginfo table
sig_name
A string representation of the signal
oldset_addr
The address of the bitmask array of blocked signals
sig
The signal number that invoked the signal handler
ka_addr
The address of the k_sigaction table associated with the signal
NAMEprobe::signal.handle.return — Signal handler invocation completed
signal.handle
SystemTap Tapset Reference
150
SYNOPSIS
VALUES
retstr
Return value as a string
name
Name of the probe point
NAMEprobe::signal.do_action — Examining or changing a signal action
SYNOPSIS
VALUES
sa_mask
The new mask of the signal
name
Name of the probe point
sig_name
A string representation of the signal
oldsigact_addr
The address of the old sigaction struct associated with the signal
sig
The signal to be examined/changed
sa_handler
The new handler of the signal
sigact_addr
The address of the new sigaction struct associated with the signal
signal.handle.return
signal.do_action
CHAPTER 14. SIGNAL TAPSET
151
NAMEprobe::signal.do_action.return — Examining or changing a signal action completed
SYNOPSIS
VALUES
retstr
Return value as a string
name
Name of the probe point
NAMEprobe::signal.procmask — Examining or changing blocked signals
SYNOPSIS
VALUES
how
Indicates how to change the blocked signals; possible values are SIG_BLOCK=0 (for blockingsignals), SIG_UNBLOCK=1 (for unblocking signals), and SIG_SETMASK=2 for setting the signalmask.
name
Name of the probe point
oldsigset_addr
The old address of the signal set (sigset_t)
sigset
The actual value to be set for sigset_t (correct?)
sigset_addr
The address of the signal set (sigset_t) to be implemented
NAMEprobe::signal.procmask.return — Examining or changing blocked signals completed
signal.do_action.return
signal.procmask
SystemTap Tapset Reference
152
SYNOPSIS
VALUES
retstr
Return value as a string
name
Name of the probe point
NAMEprobe::signal.flush — Flushing all pending signals for a task
SYNOPSIS
VALUES
name
Name of the probe point
task
The task handler of the process performing the flush
pid_name
The name of the process associated with the task performing the flush
sig_pid
The PID of the process associated with the task performing the flush
signal.procmask.return
signal.flush
CHAPTER 14. SIGNAL TAPSET
153
CHAPTER 15. DIRECTORY-ENTRY (DENTRY) TAPSETThis family of functions is used to map kernel VFS directory entry pointers to file or full path names.
NAMEfunction::d_name — get the dirent name
SYNOPSIS
ARGUMENTS
dentry
Pointer to dentry.
DESCRIPTIONReturns the dirent name (path basename).
NAMEfunction::reverse_path_walk — get the full dirent path
SYNOPSIS
ARGUMENTS
dentry
Pointer to dentry.
DESCRIPTIONReturns the path name (partial path to mount point).
NAMEfunction::task_dentry_path — get the full dentry path
SYNOPSIS
ARGUMENTS
task
function d_name:string(dentry:long)
function reverse_path_walk:string(dentry:long)
function task_dentry_path:string(task:long,dentry:long,vfsmnt:long)
SystemTap Tapset Reference
154
task
task_struct pointer.
dentry
direntry pointer.
vfsmnt
vfsmnt pointer.
DESCRIPTIONReturns the full dirent name (full path to the root), like the kernel d_path function.
NAMEfunction::d_path — get the full nameidata path
SYNOPSIS
ARGUMENTS
nd
Pointer to nameidata.
DESCRIPTIONReturns the full dirent name (full path to the root), like the kernel d_path function.
function d_path:string(nd:long)
CHAPTER 15. DIRECTORY-ENTRY (DENTRY) TAPSET
155
CHAPTER 16. LOGGING TAPSETThis family of functions is used to send simple message strings to various destinations.
NAMEfunction::log — Send a line to the common trace buffer.
SYNOPSIS
ARGUMENTS
msg
The formatted message string.
GENERAL SYNTAXlog(msg:string)
DESCRIPTIONThis function logs data. log sends the message immediately to staprun and to the bulk transport(relayfs) if it is being used. If the last character given is not a newline, then one is added. This functionis not as effecient as printf and should be used only for urgent messages.
NAMEfunction::warn — Send a line to the warning stream.
SYNOPSIS
ARGUMENTS
msg
The formatted message string.
GENERAL SYNTAXwarn (msg:string)
DESCRIPTIONThis function sends a warning message immediately to staprun. It is also sent over the bulk transport(relayfs) if it is being used. If the last characater is not a newline, the one is added.
function log(msg:string)
function warn(msg:string)
SystemTap Tapset Reference
156
NAMEfunction::exit — Start shutting down probing script.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXexit
DESCRIPTIONThis only enqueues a request to start shutting down the script. New probes will not fire (except “end”probes), but all currently running ones may complete their work.
NAMEfunction::error — Send an error message.
SYNOPSIS
ARGUMENTS
msg
The formatted message string.
DESCRIPTIONAn implicit end-of-line is added. staprun prepends the string “ERROR:”. Sending an error messageaborts the currently running probe. Depending on the MAXERRORS parameter, it may trigger an exit.
NAMEfunction::ftrace — Send a message to the ftrace ring-buffer.
SYNOPSIS
ARGUMENTS
msg
The formatted message string.
function exit()
function error(msg:string)
function ftrace(msg:string)
CHAPTER 16. LOGGING TAPSET
157
DESCRIPTIONIf the ftrace ring-buffer is configured & available, see /debugfs/tracing/trace for the message.Otherwise, the message may be quietly dropped. An implicit end-of-line is added.
SystemTap Tapset Reference
158
CHAPTER 17. RANDOM FUNCTIONS TAPSETThese functions deal with random number generation.
NAMEfunction::randint — Return a random number between [0,n)
SYNOPSIS
ARGUMENTS
n
Number past upper limit of range, not larger than 2**20.
function randint:long(n:long)
CHAPTER 17. RANDOM FUNCTIONS TAPSET
159
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONSTAPSETFunctions to retrieve strings and other primitive types from the kernel or a user space programs basedon addresses. All strings are of a maximum length given by MAXSTRINGLEN.
NAMEfunction::kernel_string — Retrieves string from kernel memory.
SYNOPSIS
ARGUMENTS
addr
The kernel address to retrieve the string from.
GENERAL SYNTAXkernel_string:string(addr:long)
DESCRIPTIONThis function returns the null terminated C string from a given kernel memory address. Reports anerror on string copy fault.
NAMEfunction::kernel_string2 — Retrieves string from kernel memory with alternative error string.
SYNOPSIS
ARGUMENTS
addr
The kernel address to retrieve the string from.
err_msg
The error message to return when data isn't available.
GENERAL SYNTAXkernel_string2:string(addr:long, err_msg:string)
DESCRIPTION
function kernel_string:string(addr:long)
function kernel_string2:string(addr:long,err_msg:string)
SystemTap Tapset Reference
160
This function returns the null terminated C string from a given kernel memory address. Reports thegiven error message on string copy fault.
NAMEfunction::kernel_string_n — Retrieves string of given length from kernel memory.
SYNOPSIS
ARGUMENTS
addr
The kernel address to retrieve the string from.
n
The maximum length of the string (if not null terminated).
GENERAL SYNTAXkernel_string_n:string(addr:long, n:long)
DESCRIPTIONReturns the C string of a maximum given length from a given kernel memory address. Reports an erroron string copy fault.
NAMEfunction::kernel_long — Retrieves a long value stored in kernel memory.
SYNOPSIS
ARGUMENTS
addr
The kernel address to retrieve the long from.
GENERAL SYNTAXkernel_long:long(addr:long)
DESCRIPTIONReturns the long value from a given kernel memory address. Reports an error when reading from thegiven address fails.
function kernel_string_n:string(addr:long,n:long)
function kernel_long:long(addr:long)
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONS TAPSET
161
NAMEfunction::kernel_int — Retrieves an int value stored in kernel memory.
SYNOPSIS
ARGUMENTS
addr
The kernel address to retrieve the int from.
DESCRIPTIONReturns the int value from a given kernel memory address. Reports an error when reading from thegiven address fails.
NAMEfunction::kernel_short — Retrieves a short value stored in kernel memory.
SYNOPSIS
ARGUMENTS
addr
The kernel address to retrieve the short from.
GENERAL SYNTAXkernel_short:long(addr:long)
DESCRIPTIONReturns the short value from a given kernel memory address. Reports an error when reading from thegiven address fails.
NAMEfunction::kernel_char — Retrieves a char value stored in kernel memory.
SYNOPSIS
ARGUMENTS
addr
function kernel_int:long(addr:long)
function kernel_short:long(addr:long)
function kernel_char:long(addr:long)
SystemTap Tapset Reference
162
addr
The kernel address to retrieve the char from.
GENERAL SYNTAXkernel_char:long(addr:long)
DESCRIPTIONReturns the char value from a given kernel memory address. Reports an error when reading from thegiven address fails.
NAMEfunction::kernel_pointer — Retrieves a pointer value stored in kernel memory.
SYNOPSIS
ARGUMENTS
addr
The kernel address to retrieve the pointer from.
GENERAL SYNTAXkernel_pointer:long(addr:long)
DESCRIPTIONReturns the pointer value from a given kernel memory address. Reports an error when reading fromthe given address fails.
NAMEfunction::user_string — Retrieves string from user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
GENERAL SYNTAXuser_string:string(addr:long)
function kernel_pointer:long(addr:long)
function user_string:string(addr:long)
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONS TAPSET
163
DESCRIPTIONReturns the null terminated C string from a given user space memory address. Reports “<unknown>”on the rare cases when userspace data is not accessible.
NAMEfunction::user_string2 — Retrieves string from user space with alternative error string.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
err_msg
The error message to return when data isn't available.
GENERAL SYNTAXuser_string2:string(addr:long, err_msg:string)
DESCRIPTIONReturns the null terminated C string from a given user space memory address. Reports the given errormessage on the rare cases when userspace data is not accessible.
NAMEfunction::user_string_warn — Retrieves string from user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
GENERAL SYNTAXuser_string_warn:string(addr:long)
DESCRIPTION
function user_string2:string(addr:long,err_msg:string)
function user_string_warn:string(addr:long)
SystemTap Tapset Reference
164
Returns the null terminated C string from a given user space memory address. Reports “<unknown>”on the rare cases when userspace data is not accessible and warns (but does not abort) about thefailure.
NAMEfunction::user_string_quoted — Retrieves and quotes string from user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
GENERAL SYNTAXuser_string_quoted:string(addr:long)
DESCRIPTIONReturns the null terminated C string from a given user space memory address where any ASCIIcharacters that are not printable are replaced by the corresponding escape sequence in the returnedstring. Reports “NULL” for address zero. Returns “<unknown>” on the rare cases when userspace datais not accessible at the given address.
NAMEfunction::user_string_n — Retrieves string of given length from user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
n
The maximum length of the string (if not null terminated).
GENERAL SYNTAXuser_string_n:string(addr:long, n:long)
DESCRIPTION
function user_string_quoted:string(addr:long)
function user_string_n:string(addr:long,n:long)
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONS TAPSET
165
Returns the C string of a maximum given length from a given user space address. Returns“<unknown>” on the rare cases when userspace data is not accessible at the given address.
NAMEfunction::user_string_n2 — Retrieves string of given length from user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
n
The maximum length of the string (if not null terminated).
err_msg
The error message to return when data isn't available.
GENERAL SYNTAXuser_string_n2:string(addr:long, n:long, err_msg:string)
DESCRIPTIONReturns the C string of a maximum given length from a given user space address. Returns the givenerror message string on the rare cases when userspace data is not accessible at the given address.
NAMEfunction::user_string_n_warn — Retrieves string from user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
n
The maximum length of the string (if not null terminated).
function user_string_n2:string(addr:long,n:long,err_msg:string)
function user_string_n_warn:string(addr:long,n:long)
SystemTap Tapset Reference
166
GENERAL SYNTAXuser_string_n_warn:string(addr:long, n:long)
DESCRIPTIONReturns up to n characters of a C string from a given user space memory address. Reports“<unknown>” on the rare cases when userspace data is not accessible and warns (but does not abort)about the failure.
NAMEfunction::user_string_n_quoted — Retrieves and quotes string from user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the string from.
n
The maximum length of the string (if not null terminated).
GENERAL SYNTAXuser_string_n_quoted:string(addr:long, n:long)
DESCRIPTIONReturns up to n characters of a C string from the given user space memory address where any ASCIIcharacters that are not printable are replaced by the corresponding escape sequence in the returnedstring. Reports “NULL” for address zero. Returns “<unknown>” on the rare cases when userspace datais not accessible at the given address.
NAMEfunction::user_short — Retrieves a short value stored in user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the short from.
function user_string_n_quoted:string(addr:long,n:long)
function user_short:long(addr:long)
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONS TAPSET
167
GENERAL SYNTAXuser_short:long(addr:long)
DESCRIPTIONReturns the short value from a given user space address. Returns zero when user space data is notaccessible.
NAMEfunction::user_short_warn — Retrieves a short value stored in user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the short from.
GENERAL SYNTAXuser_short_warn:long(addr:long)
DESCRIPTIONReturns the short value from a given user space address. Returns zero when user space and warns (butdoes not abort) about the failure.
NAMEfunction::user_int — Retrieves an int value stored in user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the int from.
GENERAL SYNTAXuser_int:long(addr:long)
DESCRIPTIONReturns the int value from a given user space address. Returns zero when user space data is notaccessible.
function user_short_warn:long(addr:long)
function user_int:long(addr:long)
SystemTap Tapset Reference
168
NAMEfunction::user_int_warn — Retrieves an int value stored in user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the int from.
GENERAL SYNTAXuser_ing_warn:long(addr:long)
DESCRIPTIONReturns the int value from a given user space address. Returns zero when user space and warns (butdoes not abort) about the failure.
NAMEfunction::user_long — Retrieves a long value stored in user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the long from.
GENERAL SYNTAXuser_long:long(addr:long)
DESCRIPTIONReturns the long value from a given user space address. Returns zero when user space data is notaccessible. Note that the size of the long depends on the architecture of the current user space task(for those architectures that support both 64/32 bit compat tasks).
NAMEfunction::user_long_warn — Retrieves a long value stored in user space.
SYNOPSIS
function user_int_warn:long(addr:long)
function user_long:long(addr:long)
function user_long_warn:long(addr:long)
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONS TAPSET
169
ARGUMENTS
addr
The user space address to retrieve the long from.
GENERAL SYNTAXuser_long_warn:long(addr:long)
DESCRIPTIONReturns the long value from a given user space address. Returns zero when user space and warns (butdoes not abort) about the failure. Note that the size of the long depends on the architecture of thecurrent user space task (for those architectures that support both 64/32 bit compat tasks).
NAMEfunction::user_char — Retrieves a char value stored in user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the char from.
GENERAL SYNTAXuser_char:long(addr:long)
DESCRIPTIONReturns the char value from a given user space address. Returns zero when user space data is notaccessible.
NAMEfunction::user_char_warn — Retrieves a char value stored in user space.
SYNOPSIS
ARGUMENTS
addr
The user space address to retrieve the char from.
function user_char:long(addr:long)
function user_char_warn:long(addr:long)
SystemTap Tapset Reference
170
GENERAL SYNTAXuser_char_warn:long(addr:long)
DESCRIPTIONReturns the char value from a given user space address. Returns zero when user space and warns (butdoes not abort) about the failure.
CHAPTER 18. STRING AND DATA RETRIEVING FUNCTIONS TAPSET
171
CHAPTER 19. A COLLECTION OF STANDARD STRINGFUNCTIONSFunctions to get the length, a substring, getting at individual characters, string seaching, escaping,tokenizing, and converting strings to longs.
NAMEfunction::strlen — Returns the length of a string.
SYNOPSIS
ARGUMENTS
s
the string
GENERAL SYNTAXstrlen: long (str:string)
DESCRIPTIONThis function returns the length of the string, which can be zero up to MAXSTRINGLEN.
NAMEfunction::substr — Returns a substring.
SYNOPSIS
ARGUMENTS
str
The string to take a substring from
start
Starting position. 0 = start of the string.
length
Length of string to return.
GENERAL SYNTAXsubstr:string (str:string, start:long, stop:long)
function strlen:long(s:string)
function substr:string(str:string,start:long,length:long)
SystemTap Tapset Reference
172
DESCRIPTIONReturns the substring of the up to the given length starting at the given start position and ending atgiven stop position.
NAMEfunction::stringat — Returns the char at a given position in the string.
SYNOPSIS
ARGUMENTS
str
The string to fetch the character from.
pos
The position to get the character from. 0 = start of the string.
GENERAL SYNTAXstringat:long(srt:string, pos:long)
DESCRIPTIONThis function returns the character at a given position in the string or zero if thestring doesn't have asmany characters.
NAMEfunction::isinstr — Returns whether a string is a substring of another string.
SYNOPSIS
ARGUMENTS
s1
String to search in.
s2
Substring to find.
GENERAL SYNTAXisinstr:long (s1:string, s2:string)
function stringat:long(str:string,pos:long)
function isinstr:long(s1:string,s2:string)
CHAPTER 19. A COLLECTION OF STANDARD STRING FUNCTIONS
173
DESCRIPTIONThis function returns 1 if string s1 contains s2, otherwise zero.
NAMEfunction::text_str — Escape any non-printable chars in a string.
SYNOPSIS
ARGUMENTS
input
The string to escape.
GENERAL SYNTAXtext_str:string (input:string)
DESCRIPTIONThis function accepts a string argument, and any ASCII characters that are not printable are replacedby the corresponding escape sequence in the returned string.
NAMEfunction::text_strn — Escape any non-printable chars in a string.
SYNOPSIS
ARGUMENTS
input
The string to escape.
len
Maximum length of string to return. 0 means MAXSTRINGLEN.
quoted
Put double quotes around the string. If input string is truncated it will have “...” after the secondquote.
GENERAL SYNTAXtext_strn:string (input:string, len:long, quoted:long)
function text_str:string(input:string)
function text_strn:string(input:string,len:long,quoted:long)
SystemTap Tapset Reference
174
DESCRIPTIONThis function accepts a string of designated length, and any ASCII characters that are not printable arereplaced by the corresponding escape sequence in the returned string.
NAMEfunction::tokenize — Return the next non-empty token in a string.
SYNOPSIS
ARGUMENTS
input
String to tokenize. If NULL, returns the next non-empty token in the string passed in the previouscall to tokenize.
delim
Token delimiter. Set of characters that delimit the tokens.
GENERAL SYNTAXtokenize:string (input:string, delim:string)
DESCRIPTIONThis function returns the next non-empty token in the given input string, where the tokens aredelimited by characters in the delim string. If the input string is non-NULL, it returns the first token. Ifthe input string is NULL, it returns the next token in the string passed in the previous call to tokenize. Ifno delimiter is found, the entire remaining input string is returned. It returns NULL when no moretokens are available.
NAMEfunction::str_replace — str_replace Replaces all instances of a substring with another.
SYNOPSIS
ARGUMENTS
prnt_str
The string to search and replace in.
srch_str
The substring which is used to search in prnt_str string.
function tokenize:string(input:string,delim:string)
function str_replace:string(prnt_str:string,srch_str:string,rplc_str:string)
CHAPTER 19. A COLLECTION OF STANDARD STRING FUNCTIONS
175
rplc_str
The substring which is used to replace srch_str.
GENERAL SYNTAXstr_replace:string(prnt_str:string, srch_str:string, rplc_str:string)
DESCRIPTIONThis function returns the given string with substrings replaced.
NAMEfunction::strtol — strtol - Convert a string to a long.
SYNOPSIS
ARGUMENTS
str
String to convert.
base
The base to use
GENERAL SYNTAXstrtol:long (str:string, base:long)
DESCRIPTIONThis function converts the string representation of a number to an integer. The base parameterindicates the number base to assume for the string (eg. 16 for hex, 8 for octal, 2 for binary).
NAMEfunction::isdigit — Checks for a digit.
SYNOPSIS
ARGUMENTS
str
String to check.
function strtol:long(str:string,base:long)
function isdigit:long(str:string)
SystemTap Tapset Reference
176
GENERAL SYNTAXisdigit:long(str:string)
DESCRIPTIONChecks for a digit (0 through 9) as the first character of a string. Returns non-zero if true, and a zero iffalse.
CHAPTER 19. A COLLECTION OF STANDARD STRING FUNCTIONS
177
CHAPTER 20. UTILITY FUNCTIONS FOR USING ANSICONTROL CHARS IN LOGSUtility functions for logging using ansi control characters. This lets you manipulate the cursor positionand character color output and attributes of log messages.
NAMEfunction::ansi_clear_screen — Move cursor to top left and clear screen.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXansi_clear_screen
DESCRIPTIONSends ansi code for moving cursor to top left and then the ansi code for clearing the screen from thecursor position to the end.
NAMEfunction::ansi_set_color — Set the ansi Select Graphic Rendition mode.
SYNOPSIS
ARGUMENTS
fg
Foreground color to set.
GENERAL SYNTAXansi_set_color(fh:long)
DESCRIPTIONSends ansi code for Select Graphic Rendition mode for the given forground color. Black (30), Blue (34),Green (32), Cyan (36), Red (31), Purple (35), Brown (33), Light Gray (37).
NAMEfunction::ansi_set_color2 — Set the ansi Select Graphic Rendition mode.
function ansi_clear_screen()
function ansi_set_color(fg:long)
SystemTap Tapset Reference
178
SYNOPSIS
ARGUMENTS
fg
Foreground color to set.
bg
Background color to set.
GENERAL SYNTAXansi_set_color2(fg:long, bg:long)
DESCRIPTIONSends ansi code for Select Graphic Rendition mode for the given forground color, Black (30), Blue (34),Green (32), Cyan (36), Red (31), Purple (35), Brown (33), Light Gray (37) and the given backgroundcolor, Black (40), Red (41), Green (42), Yellow (43), Blue (44), Magenta (45), Cyan (46), White (47).
NAMEfunction::ansi_set_color3 — Set the ansi Select Graphic Rendition mode.
SYNOPSIS
ARGUMENTS
fg
Foreground color to set.
bg
Background color to set.
attr
Color attribute to set.
GENERAL SYNTAXansi_set_color3(fg:long, bg:long, attr:long)
DESCRIPTIONSends ansi code for Select Graphic Rendition mode for the given forground color, Black (30), Blue (34),Green (32), Cyan (36), Red (31), Purple (35), Brown (33), Light Gray (37), the given background color,Black (40), Red (41), Green (42), Yellow (43), Blue (44), Magenta (45), Cyan (46), White (47) and the
function ansi_set_color2(fg:long,bg:long)
function ansi_set_color3(fg:long,bg:long,attr:long)
CHAPTER 20. UTILITY FUNCTIONS FOR USING ANSI CONTROL CHARS IN LOGS
179
color attribute All attributes off (0), Intensity Bold (1), Underline Single (4), Blink Slow (5), Blink Rapid(6), Image Negative (7).
NAMEfunction::ansi_reset_color — Resets Select Graphic Rendition mode.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXansi_reset_color
DESCRIPTIONSends ansi code to reset foreground, background and color attribute to default values.
NAMEfunction::ansi_new_line — Move cursor to new line.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXansi_new_line
DESCRIPTIONSends ansi code new line.
NAMEfunction::ansi_cursor_move — Move cursor to new coordinates.
SYNOPSIS
ARGUMENTS
x
function ansi_reset_color()
function ansi_new_line()
function ansi_cursor_move(x:long,y:long)
SystemTap Tapset Reference
180
x
Row to move the cursor to.
y
Colomn to move the cursor to.
GENERAL SYNTAXansi_curos_move(x:long, y:long)
DESCRIPTIONSends ansi code for positioning the cursor at row x and column y. Coordinates start at one, (1,1) is thetop-left corner.
NAMEfunction::ansi_cursor_hide — Hides the cursor.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXansi_cusor_hide
DESCRIPTIONSends ansi code for hiding the cursor.
NAMEfunction::ansi_cursor_save — Saves the cursor position.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXansi_cursor_save
DESCRIPTIONSends ansi code for saving the current cursor position.
function ansi_cursor_hide()
function ansi_cursor_save()
CHAPTER 20. UTILITY FUNCTIONS FOR USING ANSI CONTROL CHARS IN LOGS
181
NAMEfunction::ansi_cursor_restore — Restores a previously saved cursor position.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXansi_cursor_restore
DESCRIPTIONSends ansi code for restoring the current cursor position previously saved with ansi_cursor_save.
NAMEfunction::ansi_cursor_show — Shows the cursor.
SYNOPSIS
ARGUMENTSNone
GENERAL SYNTAXansi_cursor_show
DESCRIPTIONSends ansi code for showing the cursor.
function ansi_cursor_restore()
function ansi_cursor_show()
SystemTap Tapset Reference
182