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.

http://creativecommons.org/licenses/by-sa/3.0/

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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


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


4

DESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSDESCRIPTIONNOTENAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTS

4848484848484848484849494949494949494949494950505050505050505050505051515151515151515151515252525252525252

Table of Contents

5

GENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTIONNAMESYNOPSISARGUMENTS

5252525252535353535353535353535354545454545454545454545455555555555555555555555556565656565656565656565657


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


8

VALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISVALUESNAMESYNOPSISVALUESDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSIS

676868686969696970707070707071717171717171

7272727272727272727272727373737373737373737373747474747474747474

Table of Contents

9

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTION

CHAPTER 7. TASK TIME TAPSETNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTS

74747575757575757575757575767676767676767676767677

787878787878787878787878797979797979797979797980808080


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


12

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

NAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUES

CHAPTER 11. NETWORKING TAPSETNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUES

999999

100100100101101101101101101102102102102102102103103103103103103104104104104104104

105105105105105105105106106106106106106106106106107107107107107107

Table of Contents

13

NAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXT

107107108108108108108108108109109109109109109109109109110110110110110110110111111111111111111111112112112112112112112113113113113113113114114114114114114114115


14

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

NAMESYNOPSISVALUESNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISARGUMENTS

CHAPTER 12. SOCKET TAPSETNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUES

115115115116116116116116116116117117117117117117117117117118118118118118118118118118118119

120120120120120120120121121121121121122122122122122123123123123123

Table of Contents

15

CONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAME

124124124124124124125125125125125125125125126126126126126126127127127127127128128128128128129129129129129130130130130130130130130131131131131131131132132132132


16

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

SYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTSDESCRIPTIONNAMESYNOPSISARGUMENTSNAMESYNOPSISARGUMENTS

CHAPTER 13. KERNEL PROCESS TAPSETNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUES

132132133133133133133133134134134134134134134134134134134134135135135135135135135135135135136136136

137137137137137137137137137137137137137138138138138138138

Table of Contents

17

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTIONNAMESYNOPSISVALUESCONTEXTDESCRIPTION

CHAPTER 14. SIGNAL TAPSETNAMESYNOPSISVALUESCONTEXTNAMESYNOPSISVALUESCONTEXTDESCRIPTIONWHICH MEANS THATNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSISVALUESNAMESYNOPSIS

138138138138138139139139139139139139

140140140140140141141141141141141142142142142142142143143143143143143144144144144144144145145145145145145145146146146146


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


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


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


24

NAMESYNOPSISARGUMENTSGENERAL SYNTAXDESCRIPTION

182182182182182

Table of Contents

25

PREFACE


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}


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> */


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()


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()


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()


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()


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()


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()


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()


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()


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)


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)


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)


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()


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


function modname:string(addr:long)

function symname:string(addr:long)

function symdata:string(addr:long)


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


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


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)


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)


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()


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()


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()


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).


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).


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.


function print_ubacktrace_brief()

function ubacktrace:string()


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)


52

task


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


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


GENERAL SYNTAXtask_pid:long (task:long)

function task_execname:string(task:long)

function task_pid:long(task:long)


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)


54

task


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


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


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)


55

NAMEfunction::task_uid — The user identifier of the task.

SYNOPSIS

ARGUMENTS

task


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


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)


56

ARGUMENTS

task


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


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


GENERAL SYNTAXtask_cpu:long(task:long)

function task_nice:long(task:long)

function task_cpu:long(task:long)


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


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


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)


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()


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()


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)


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


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


64

name


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


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


65

VALUES

length

The length of the memory segment

name


address

The requested address

CONTEXTThe process calling mmap.

NAMEprobe::vm.munmap — Fires when an munmap is requested.

SYNOPSIS

VALUES

length


name


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


66

length


name


address


CONTEXTThe process calling brk.

NAMEprobe::vm.oom_kill — Fires when a thread is selected for termination by the OOM killer.

SYNOPSIS

VALUES

name


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


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


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


caller_function


call_site

Address of the function calling this kmemory function.

gfp_flag_name

Type of kmemory to allocate(in string format)

name


vm.kmem_cache_alloc


68

bytes_req

Requested Bytes

bytes_alloc

Allocated Bytes

gfp_flags


DESCRIPTIONkmem_cache_alloc is requested.

NAMEprobe::vm.kmalloc_node — Fires when kmalloc_node is requested.

SYNOPSIS

VALUES

ptr


caller_function


call_site

Address of the function caling this kmemory function.

gfp_flag_name


name


bytes_req

Requested Bytes

bytes_alloc

Allocated Bytes

gfp_flags


vm.kmalloc_node


69

NAMEprobe::vm.kmem_cache_alloc_node — Fires when \

SYNOPSIS

VALUES

ptr


caller_function


call_site


gfp_flag_name


name


bytes_req

Requested Bytes

bytes_alloc

Allocated Bytes

gfp_flags


DESCRIPTIONkmem_cache_alloc_node is requested.

NAMEprobe::vm.kfree — Fires when kfree is requested.

SYNOPSIS

vm.kmem_cache_alloc_node

vm.kfree


70

VALUES

ptr

Pointer to the kmemory allocated which is returned by kmalloc

caller_function


call_site


name


NAMEprobe::vm.kmem_cache_free — Fires when \

SYNOPSIS

VALUES

ptr

Pointer to the kmemory allocated which is returned by kmem_cache

caller_function


call_site


name


DESCRIPTIONkmem_cache_free is requested.

NAMEfunction::proc_mem_size — Total program virtual memory size in pages

SYNOPSIS

vm.kmem_cache_free


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()


72

ARGUMENTS

pid


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


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)


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


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()


74

NAMEfunction::proc_mem_data_pid — Program data size (data + stack) in pages

SYNOPSIS

ARGUMENTS

pid


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)


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


function pages_to_string:string(pages:long)

function proc_mem_string:string()

function proc_mem_string_pid:string(pid:long)


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 ”.


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()


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


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)


80

ARGUMENTS

tid


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


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


disk_minor

Disk minor number of the request

rq_flags

Request flags

ioscheduler.elv_next_request

ioscheduler.elv_next_request.return


82

NAMEprobe::ioscheduler.elv_completed_request — Fires when a request is completed

SYNOPSIS

VALUES

disk_major


rq


name


elevator_name


disk_minor


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


rq


q

pointer to request queue

ioscheduler.elv_completed_request

ioscheduler.elv_add_request.kp

CHAPTER 8. IO SCHEDULER AND BLOCK IO TAPSET

83

name


elevator_name


disk_minor


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


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


84

NAMEprobe::ioscheduler.elv_add_request — probe to indicate request is added to the request queue.

SYNOPSIS

VALUES

disk_major


rq

Address of request.

q

Pointer to request queue.

elevator_name


disk_minor


rq_flags

Request flags.

NAMEprobe::ioscheduler_trace.elv_completed_request — Fires when a request is

SYNOPSIS

VALUES

disk_major


rq

Address of request.

name


ioscheduler.elv_add_request

ioscheduler_trace.elv_completed_request


85

elevator_name


disk_minor


rq_flags

Request flags.

DESCRIPTIONcompleted.

NAMEprobe::ioscheduler_trace.elv_issue_request — Fires when a request is

SYNOPSIS

VALUES

disk_major


rq

Address of request.

name


elevator_name


disk_minor


rq_flags

Request flags.

DESCRIPTIONscheduled.

ioscheduler_trace.elv_issue_request


86

NAMEprobe::ioscheduler_trace.elv_requeue_request — Fires when a request is

SYNOPSIS

VALUES

disk_major


rq

Address of request.

name


elevator_name


disk_minor


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


rq

Address of request.

ioscheduler_trace.elv_requeue_request

ioscheduler_trace.elv_abort_request


87

name


elevator_name


disk_minor


rq_flags

Request flags.

NAMEprobe::ioscheduler_trace.plug — Fires when a request queue is plugged;

SYNOPSIS

VALUES

name


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


rq_queue

ioscheduler_trace.plug

ioscheduler_trace.unplug_io


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


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


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


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


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.


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


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


data_direction_str

Data direction, as a string

req_addr


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


dev_id

The scsi device id

channel

The channel number

scsi.iodone


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


device_state


scsi_timer_pending

1 if a timer is pending on this request

req_addr


NAMEprobe::scsi.iocompleted — SCSI mid-layer running the completion processing for block device I/Orequests

SYNOPSIS

VALUES

device_state_str


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


95

The lun number

host_no

The host number

data_direction_str


device_state


req_addr


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


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


96

timeout

Request timeout in seconds

request_bufflen

The data buffer buffer length

host_no

The host number

data_direction_str


device_state


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


lun

The lun number

scsi.set_state


97

old_state


host_no

The host number


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


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


101

NAMEprobe::tty.register — Called when a tty device is registred

SYNOPSIS

VALUES

driver_name

the driver 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


index

the tty index requested

module

the module name

tty.register

tty.unregister


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


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


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


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


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


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


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


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


111

sock

Network socket

CONTEXTThe process which receives a tcp message

NAMEprobe::tcp.recvmsg.return — Receiving TCP message complete

SYNOPSIS

VALUES

saddr


daddr


name

Name of this probe

sport

TCP source port

dport


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


112

VALUES

saddr


daddr


flags

TCP flags (e.g. FIN, etc)

name

Name of this probe

sport

TCP source port

dport


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


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


name

Name of this probe

tcp.setsockopt

tcp.setsockopt.return


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


rst

TCP RST flag

dport


saddr


daddr


ack

TCP ACK flag

fin

TCP FIN flag

syn

TCP SYN flag

tcp.receive


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


size

Number of bytes sent by the process

udp.sendmsg

udp.sendmsg.return


116

CONTEXTThe process which sent a UDP message

NAMEprobe::udp.recvmsg — Fires whenever a UDP message is received

SYNOPSIS

VALUES

name


size

Number of bytes received by the process

sock


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


size

Number of bytes received by the process

CONTEXTThe process which received a UDP message

udp.recvmsg

udp.recvmsg.return


117

NAMEprobe::udp.disconnect — Fires when a process requests for a UDP disconnection

SYNOPSIS

VALUES

flags

Flags (e.g. FIN, etc)

name


sock


CONTEXTThe process which requests a UDP disconnection

NAMEprobe::udp.disconnect.return — UDP has been disconnected successfully

SYNOPSIS

VALUES

ret


name


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


118

ARGUMENTS

addr

the ip represented as an integer

function ip_ntop:string(addr:long)


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


120

VALUES

success


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


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



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


protocol

Protocol value

flags

Socket flags value

name

Name of this probe

state

socket.sendmsg.return


122

Socket state value

size


type

Socket type value

family


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


type

Socket type value

family

socket.recvmsg


123


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


type

Socket type value

family



socket.recvmsg.return


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


type

Socket type value

family



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


125

VALUES

success


protocol

Protocol value

flags

Socket flags value

name

Name of this probe

state

Socket state value

size


type

Socket type value

family



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


126

Protocol value

flags

Socket flags value

name

Name of this probe

state

Socket state value

size


type

Socket type value

family



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


protocol

Protocol value

flags

Socket flags value

name

socket.aio_read.return


127

Name of this probe

state

Socket state value

size


type

Socket type value

family



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


type

socket.writev


128

Socket type value

family



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


protocol

Protocol value

flags

Socket flags value

name

Name of this probe

state

Socket state value

size


type

Socket type value

family


socket.writev.return


129


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


type

Socket type value

family



DESCRIPTIONFires at the beginning of receiving a message on a socket via the sock_readv function

NAME

socket.readv


130

probe::socket.readv.return — Conclusion of receiving a message via sock_readv

SYNOPSIS

VALUES

success


protocol

Protocol value

flags

Socket flags value

name

Name of this probe

state

Socket state value

size


type

Socket type value

family



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


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


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


132

Requested by user process or the kernel (1 = kernel, 0 = user)

type

Socket type value

family


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



socket.close


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


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)


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)


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)


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


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


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


task

A task handle to the signal recipient

sinfo

The address of the siginfo structure

si_code

Indicates the signal type

sig_name


sig


pid_name

Name of the process receiving the signal

sig_pid


NAMEprobe::signal.checkperm.return — Check performed on a sent signal completed

SYNOPSIS

VALUES

retstr

Return value as a string

signal.checkperm

signal.checkperm.return


142

name


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


sig


pid_name


signal.wakeup

signal.check_ignored


143

sig_pid


NAMEprobe::signal.check_ignored.return — Check to see signal is ignored completed

SYNOPSIS

VALUES

retstr


name


NAMEprobe::signal.force_segv — Forcing send of SIGSEGV

SYNOPSIS

VALUES

name


sig_name


sig


pid_name


sig_pid


signal.check_ignored.return

signal.force_segv


144

NAMEprobe::signal.force_segv.return — Forcing send of SIGSEGV complete

SYNOPSIS

VALUES

retstr


name


NAMEprobe::signal.syskill — Sending kill signal to a process

SYNOPSIS

VALUES

name


sig_name


sig

The specific signal sent to the process

pid_name


sig_pid


NAMEprobe::signal.syskill.return — Sending kill signal completed

signal.force_segv.return

signal.syskill


145

SYNOPSIS

VALUESNone

NAMEprobe::signal.sys_tkill — Sending a kill signal to a thread

SYNOPSIS

VALUES

name


sig_name


sig

The specific signal sent to the process

pid_name


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


146

retstr

The return value to either __group_send_sig_info,

name


NAMEprobe::signal.sys_tgkill — Sending kill signal to a thread group

SYNOPSIS

VALUES

name


sig_name


sig

The specific kill signal sent to the process

tgid

The thread group ID of the thread receiving the kill signal

pid_name


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


147

VALUES

retstr

The return value to either __group_send_sig_info,

name


NAMEprobe::signal.send_sig_queue — Queuing a signal to a process

SYNOPSIS

VALUES

sigqueue_addr

The address of the signal queue

name


sig_name


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


148

VALUES

retstr


name


NAMEprobe::signal.pending — Examining pending signal

SYNOPSIS

VALUES

name


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


signal.send_sig_queue.return

signal.pending

signal.pending.return


149

name


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


sig_mode

Indicates whether the signal was a user-mode or kernel-mode signal

sinfo

The address of the siginfo table

sig_name


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


150

SYNOPSIS

VALUES

retstr


name


NAMEprobe::signal.do_action — Examining or changing a signal action

SYNOPSIS

VALUES

sa_mask

The new mask of the signal

name


sig_name


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


151

NAMEprobe::signal.do_action.return — Examining or changing a signal action completed

SYNOPSIS

VALUES

retstr


name


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


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


152

SYNOPSIS

VALUES

retstr


name


NAMEprobe::signal.flush — Flushing all pending signals for a task

SYNOPSIS

VALUES

name


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


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)


154

task


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


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)


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


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


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.


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


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)


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


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)


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)


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


err_msg


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


GENERAL SYNTAXuser_string_warn:string(addr:long)

DESCRIPTION

function user_string2:string(addr:long,err_msg:string)

function user_string_warn:string(addr:long)


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


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


n


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)


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


n


err_msg


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


n


function user_string_n2:string(addr:long,n:long,err_msg:string)

function user_string_n_warn:string(addr:long,n:long)


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


n


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)


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)


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)


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)


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.


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)


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)


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)


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)


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.


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)


178

SYNOPSIS

ARGUMENTS

fg


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


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)


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()


182

Documents

Red Hat Enterprise Linux 6.8 SystemTap Tapset Reference