1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html > <head><title>Probe points</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="generator" content="TeX4ht (https://tug.org/tex4ht/)"> <meta name="originator" content="TeX4ht (https://tug.org/tex4ht/)"> <!-- html,2 --> <meta name="src" content="langref.tex"> <link rel="stylesheet" type="text/css" href="langref.css"> </head><body > <!--l. 891--><div class="crosslinks"><p class="noindent">[<a href="langrefse5.html" >next</a>] [<a href="langrefse3.html" >prev</a>] [<a href="langrefse3.html#taillangrefse3.html" >prev-tail</a>] [<a href="#taillangrefse4.html">tail</a>] [<a href="langref.html#langrefse4.html" >up</a>] </p></div> <h3 class="sectionHead"><span class="titlemark">4 </span> <a id="x6-300004"></a>Probe points</h3> <a id="dx6-30001"></a> <!--l. 893--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.1 </span> <a id="x6-310004.1"></a>General syntax</h4> <a id="dx6-31001"></a> <!--l. 895--><p class="noindent" >The general probe point syntax is a dotted-symbol sequence. This divides the event namespace into parts, analogous to the style of the Domain Name System. Each component identifier is parameterized by a string or number literal, with a syntax analogous to a function call. <!--l. 900--><p class="noindent" >The following are all syntactically valid probe points. <!--l. 902--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 902--><p class="indent" > <pre class="verbatim" id="verbatim-33"> kernel.function("foo") kernel.function("foo").return module{"ext3"}.function("ext3_*") kernel.function("no_such_function") ? syscall.* end timer.ms(5000) </pre> <!--l. 911--><p class="nopar" ></dd></dl> <!--l. 914--><p class="noindent" >Probes may be broadly classified into <span class="cmti-10">synchronous</span><a id="dx6-31002"></a> or <span class="cmti-10">asynchronous</span>.<a id="dx6-31003"></a> A synchronous event occurs when any processor executes an instruction matched by the specification. This gives these probes a reference point (instruction address) from which more contextual data may be available. Other families of probe points refer to asynchronous events such as timers, where no fixed reference point is related. Each probe point specification may match multiple locations, such as by using wildcards or aliases, and all are probed. A probe declaration may contain several specifications separated by commas, which are all probed. <!--l. 924--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.1.1 </span> <a id="x6-320004.1.1"></a>Prefixes</h5> <a id="dx6-32001"></a> <!--l. 926--><p class="noindent" >Prefixes specify the probe target, such as <span class="cmbx-10">kernel</span>, <span class="cmbx-10">module</span>, <span class="cmbx-10">timer</span>, and so on. <!--l. 929--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.1.2 </span> <a id="x6-330004.1.2"></a>Suffixes</h5> <a id="dx6-33001"></a> <!--l. 931--><p class="noindent" >Suffixes further qualify the point to probe, such as <span class="cmbx-10">.return </span>for the exit point of a probed function. The absence of a suffix implies the function entry point. <!--l. 935--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.1.3 </span> <a id="x6-340004.1.3"></a>Wildcarded file names, function names</h5> <a id="dx6-34001"></a> <!--l. 937--><p class="noindent" >A component may include an asterisk (*) character, which expands to other matching probe points. An example follows. <!--l. 940--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 940--><p class="indent" > <pre class="verbatim" id="verbatim-34"> kernel.syscall.* kernel.function("sys_*) </pre> <!--l. 944--><p class="nopar" ></dd></dl> <!--l. 947--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.1.4 </span> <a id="x6-350004.1.4"></a>Optional probe points</h5> <a id="dx6-35001"></a> <!--l. 949--><p class="noindent" >A probe point may be followed by a question mark (?) character, to indicate that it is optional, and that no error should result if it fails to expand. This effect passes down through all levels of alias or wildcard expansion. <!--l. 953--><p class="noindent" >The following is the general syntax. <!--l. 955--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 955--><p class="indent" > <pre class="verbatim" id="verbatim-35"> kernel.function("no_such_function") ? </pre> <!--l. 958--><p class="nopar" ></dd></dl> <!--l. 961--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.1.5 </span> <a id="x6-360004.1.5"></a>Brace expansion</h5> <a id="dx6-36001"></a> <!--l. 963--><p class="noindent" >Brace expansion is a mechanism which allows a list of probe points to be generated. It is very similar to shell expansion. A component may be surrounded by a pair of curly braces to indicate that the comma-separated sequence of one or more subcomponents will each constitute a new probe point. The braces may be arbitrarily nested. The ordering of expanded results is based on product order. <!--l. 970--><p class="noindent" >The question mark (?), exclamation mark (!) indicators and probe point conditions may not be placed in any expansions that are before the last component. <!--l. 973--><p class="noindent" >The following is an example of brace expansion. <!--l. 975--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 975--><p class="indent" > <pre class="verbatim" id="verbatim-36"> syscall.{write,read} # Expands to syscall.write, syscall.read {kernel,module("nfs")}.function("nfs*")! # Expands to kernel.function("nfs*")!, module("nfs").function("nfs*")! </pre> <!--l. 984--><p class="nopar" ></dd></dl> <!--l. 987--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.2 </span> <a id="x6-370004.2"></a>Built-in probe point types (DWARF probes)</h4> <a id="dx6-37001"></a> <a id="dx6-37002"></a> <!--l. 991--><p class="noindent" >This family of probe points uses symbolic debugging information for the target kernel or module, as may be found in executables that have not been stripped, or in the separate <span class="cmbx-10">debuginfo </span>packages. They allow logical placement of probes into the execution path of the target by specifying a set of points in the source or object code. When a matching statement executes on any processor, the probe handler is run in that context. <!--l. 998--><p class="noindent" >Points in a kernel are identified by module, source file, line number, function name or some combination of these. <!--l. 1001--><p class="noindent" >Here is a list of probe point specifications currently supported: <!--l. 1003--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1003--><p class="indent" > <pre class="verbatim" id="verbatim-37"> kernel.function(PATTERN) kernel.function(PATTERN).call kernel.function(PATTERN).return kernel.function(PATTERN).return.maxactive(VALUE) kernel.function(PATTERN).inline kernel.function(PATTERN).label(LPATTERN) module(MPATTERN).function(PATTERN) module(MPATTERN).function(PATTERN).call module(MPATTERN).function(PATTERN).return.maxactive(VALUE) module(MPATTERN).function(PATTERN).inline kernel.statement(PATTERN) kernel.statement(ADDRESS).absolute module(MPATTERN).statement(PATTERN) </pre> <!--l. 1018--><p class="nopar" ></dd></dl> <!--l. 1021--><p class="noindent" >The <span class="cmbx-10">.function </span>variant places a probe near the beginning of the named function, so that parameters are available as context variables. <!--l. 1024--><p class="noindent" >The <span class="cmbx-10">.return </span>variant places a probe at the moment of return from the named function, so the return value is available as the <span class="tcrm-1000">$</span>return context variable. The entry parameters are also available, though the function may have changed their values. Return probes may be further qualified with <span class="cmbx-10">.maxactive</span>, which specifies how many instances of the specified function can be probed simultaneously. You can leave off <span class="cmbx-10">.maxactive </span>in most cases, as the default (<span class="cmbx-10">KRETACTIVE</span>) should be sufficient. However, if you notice an excessive number of skipped probes, try setting <span class="cmbx-10">.maxactive </span>to incrementally higher values to see if the number of skipped probes decreases. <!--l. 1034--><p class="noindent" >The <span class="cmbx-10">.inline </span>modifier for <span class="cmbx-10">.function </span>filters the results to include only instances of inlined functions. The <span class="cmbx-10">.call</span> modifier selects the opposite subset. The <span class="cmbx-10">.exported </span>modifier filters the results to include only exported functions. Inline functions do not have an identifiable return point, so <span class="cmbx-10">.return </span>is not supported on <span class="cmbx-10">.inline</span> probes. <!--l. 1040--><p class="noindent" >The <span class="cmbx-10">.statement </span>variant places a probe at the exact spot, exposing those local variables that are visible there. <!--l. 1043--><p class="noindent" >In the above probe descriptions, MPATTERN stands for a string literal that identifies the loaded kernel module of interest and LPATTERN stands for a source program label. Both MPATTERN and LPATTERN may include asterisk (*), square brackets ”[]”, and question mark (?) wildcards. <!--l. 1049--><p class="noindent" >PATTERN stands for a string literal that identifies a point in the program. It is composed of three parts: <!--l. 1052--><p class="noindent" > <ol class="enumerate1" > <li class="enumerate" id="x6-37004x1"> <!--l. 1053--><p class="noindent" >The first part is the name of a function, as would appear in the nm program’s output. This part may use the asterisk and question mark wildcard operators to match multiple names. </li> <li class="enumerate" id="x6-37006x2"> <!--l. 1056--><p class="noindent" >The second part is optional, and begins with the ampersand (@) character. It is followed by the path to the source file containing the function, which may include a wildcard pattern, such as mm/slab*. In most cases, the path should be relative to the top of the linux source directory, although an absolute path may be necessary for some kernels. If a relative pathname doesn’t work, try absolute. </li> <li class="enumerate" id="x6-37008x3"> <!--l. 1062--><p class="noindent" >The third part is optional if the file name part was given. It identifies the line number in the source file, preceded by a “:” or “+”. The line number is assumed to be an absolute line number if preceded by a “:”, or relative to the entry of the function if preceded by a “+”. All the lines in the function can be matched with “:*”. A range of lines x through y can be matched with “:x-y”. </li></ol> <!--l. 1071--><p class="noindent" >Alternately, specify PATTERN as a numeric constant to indicate a relative module address or an absolute kernel address. <!--l. 1074--><p class="noindent" >Some of the source-level variables, such as function parameters, locals, or globals visible in the compilation unit, are visible to probe handlers. Refer to these variables by prefixing their name with a dollar sign within the scripts. In addition, a special syntax allows limited traversal of structures, pointers, arrays, taking the address of a variable or pretty printing a whole structure. <!--l. 1081--><p class="noindent" ><span class="tctt-1000">$</span><span class="cmtt-10">var </span>refers to an in-scope variable var. If it is a type similar to an integer, it will be cast to a 64-bit integer for script use. Pointers similar to a string (char *) are copied to SystemTap string values by the <span class="cmtt-10">kernel</span><span class="cmtt-10">_string() </span>or <span class="cmtt-10">user</span><span class="cmtt-10">_string() </span>functions. <!--l. 1086--><p class="noindent" ><span class="cmtt-10">@var("varname") </span>is an alternative syntax for <span class="tctt-1000">$</span><span class="cmtt-10">varname</span>. It can also be used to access global variables in a particular compile unit (CU). <span class="cmtt-10">@var("varname@src/file.c") </span>refers to the global (either file local or external) variable varname defined when the file src/file.c was compiled. The CU in which the variable is resolved is the first CU in the module of the probe point which matches the given file name at the end and has the shortest file name path (e.g. given <span class="cmtt-10">@var("foo@bar/baz.c") </span>and CUs with file name paths <span class="cmtt-10">src/sub/module/bar/baz.c </span>and <span class="cmtt-10">src/bar/baz.c </span>the second CU will be chosen to resolve <span class="cmtt-10">foo</span>). <!--l. 1097--><p class="noindent" >The notation <span class="cmtt-10">@var("varname", "/path/to/exe-or-so) </span>is also supported to explicitly specify an executable or library file path in which the global or top-level static variable resides. <!--l. 1101--><p class="noindent" ><span class="tctt-1000">$</span><span class="cmtt-10">var->field </span>or <span class="cmtt-10">@var("var@file.c")->field </span>traverses a structure’s field. The indirection operator may be repeated to follow additional levels of pointers. <!--l. 1105--><p class="noindent" ><span class="tctt-1000">$</span><span class="cmtt-10">var[N] </span>or <span class="cmtt-10">@var("var@file.c")[N] </span>indexes into an array. The index is given with a literal number. <!--l. 1108--><p class="noindent" ><span class="cmtt-10">&</span><span class="tctt-1000">$</span><span class="cmtt-10">var </span>or <span class="cmtt-10">&@var("var@file.c") </span>provides the address of a variable as a long. It can also be used in combination with field access or array indexing to provide the address of a particular field or an element in an array with <span class="cmtt-10">&var->field</span>, <span class="cmtt-10">&@var("var@file.c")[N] </span>or a combination of those accessors. <!--l. 1114--><p class="noindent" >Using a single <span class="tctt-1000">$ </span>or a double <span class="tctt-1000">$$ </span>suffix provides a shallow or deep string representation of the variable data type. Using a single <span class="tctt-1000">$</span>, as in <span class="tctt-1000">$</span><span class="cmtt-10">var</span><span class="tctt-1000">$</span>, will provide a string that only includes the values of all basic type values of fields of the variable structure type but not any nested complex type values (which will be represented with <span class="cmsy-10">{</span><span class="cmtt-10">...</span><span class="cmsy-10">}</span>). Using a double <span class="tctt-1000">$$</span>, as in <span class="cmtt-10">@var("var")</span><span class="tctt-1000">$$ </span>will provide a string that also includes all values of nested data types. <!--l. 1123--><p class="noindent" ><span class="tctt-1000">$$</span><span class="cmtt-10">vars </span>expands to a character string that is equivalent to <span class="cmtt-10">sprintf("parm1=%x ... parmN=%x var1=%x ...</span> <span class="cmtt-10">varN=%x", </span><span class="tctt-1000">$</span><span class="cmtt-10">parm1, ..., </span><span class="tctt-1000">$</span><span class="cmtt-10">parmN, </span><span class="tctt-1000">$</span><span class="cmtt-10">var1, ..., </span><span class="tctt-1000">$</span><span class="cmtt-10">varN)</span> <!--l. 1127--><p class="noindent" ><span class="tctt-1000">$$</span><span class="cmtt-10">locals </span>expands to a character string that is equivalent to <span class="cmtt-10">sprintf("var1=%x ... varN=%x", </span><span class="tctt-1000">$</span><span class="cmtt-10">var1, ...,</span> <span class="tctt-1000">$</span><span class="cmtt-10">varN)</span> <!--l. 1130--><p class="noindent" ><span class="tctt-1000">$$</span><span class="cmtt-10">parms </span>expands to a character string that is equivalent to <span class="cmtt-10">sprintf("parm1=%x ... parmN=%x", </span><span class="tctt-1000">$</span><span class="cmtt-10">parm1, ...,</span> <span class="tctt-1000">$</span><span class="cmtt-10">parmN)</span> <!--l. 1134--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.2.1 </span> <a id="x6-380004.2.1"></a>kernel.function, module().function</h5> <a id="dx6-38001"></a> <a id="dx6-38002"></a> <!--l. 1137--><p class="noindent" >The <span class="cmbx-10">.function </span>variant places a probe near the beginning of the named function, so that parameters are available as context variables. <!--l. 1140--><p class="noindent" >General syntax: <!--l. 1142--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1142--><p class="indent" > <pre class="verbatim" id="verbatim-38"> kernel.function("func[@file]") module("modname").function("func[@file]") </pre> <!--l. 1146--><p class="nopar" ></dd></dl> <!--l. 1148--><p class="noindent" >Examples: <!--l. 1150--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1150--><p class="indent" > <pre class="verbatim" id="verbatim-39"> # Refers to all kernel functions with "init" or "exit" # in the name: kernel.function("*init*"), kernel.function("*exit*") # Refers to any functions within the "kernel/time.c" # file that span line 240: kernel.function("*@kernel/time.c:240") # Refers to all functions in the ext3 module: module("ext3").function("*") </pre> <!--l. 1162--><p class="nopar" ></dd></dl> <!--l. 1165--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.2.2 </span> <a id="x6-390004.2.2"></a>kernel.statement, module().statement</h5> <a id="dx6-39001"></a> <a id="dx6-39002"></a> <!--l. 1168--><p class="noindent" >The <span class="cmbx-10">.statement </span>variant places a probe at the exact spot, exposing those local variables that are visible there. <!--l. 1171--><p class="noindent" >General syntax: <!--l. 1173--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1173--><p class="indent" > <pre class="verbatim" id="verbatim-40"> kernel.statement("func@file:linenumber") module("modname").statement("func@file:linenumber") </pre> <!--l. 1177--><p class="nopar" ></dd></dl> <!--l. 1179--><p class="noindent" >Example: <!--l. 1181--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1181--><p class="indent" > <pre class="verbatim" id="verbatim-41"> # Refers to the statement at line 296 within the # kernel/time.c file: kernel.statement("*@kernel/time.c:296") # Refers to the statement at line bio_init+3 within the fs/bio.c file: kernel.statement("bio_init@fs/bio.c+3") </pre> <!--l. 1188--><p class="nopar" ></dd></dl> <!--l. 1192--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.3 </span> <a id="x6-400004.3"></a>Function return probes</h4> <a id="dx6-40001"></a> <!--l. 1194--><p class="noindent" >The <span class="cmtt-10">.return </span>variant places a probe at the moment of return from the named function, so that the return value is available as the <span class="tcrm-1000">$</span>return context variable. The entry parameters are also accessible in the context of the return probe, though their values may have been changed by the function. Inline functions do not have an identifiable return point, so <span class="cmtt-10">.return </span>is not supported on <span class="cmtt-10">.inline </span>probes. <!--l. 1201--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.4 </span> <a id="x6-410004.4"></a>DWARF-less probing</h4> <a id="dx6-41001"></a> <!--l. 1204--><p class="noindent" >In the absence of debugging information, you can still use the <span class="cmti-10">kprobe </span>family of probes to examine the entry and exit points of kernel and module functions. You cannot look up the arguments or local variables of a function using these probes. However, you can access the parameters by following this procedure: <!--l. 1210--><p class="noindent" >When you’re stopped at the entry to a function, you can refer to the function’s arguments by number. For example, when probing the function declared: <!--l. 1214--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1214--><p class="indent" > <pre class="verbatim" id="verbatim-42"> asmlinkage ssize_t sys_read(unsigned int fd, char __user * buf, size_t count) </pre> <!--l. 1218--><p class="nopar" ></dd></dl> <!--l. 1221--><p class="noindent" >You can obtain the values of <span class="cmtt-10">fd</span>, <span class="cmtt-10">buf</span>, and <span class="cmtt-10">count</span>, respectively, as <span class="cmtt-10">uint</span><span class="cmtt-10">_arg(1)</span>, <span class="cmtt-10">pointer</span><span class="cmtt-10">_arg(2)</span>, and <span class="cmtt-10">ulong</span><span class="cmtt-10">_arg(3)</span>. In this case, your probe code must first call <span class="cmtt-10">asmlinkage()</span>, because on some architectures the asmlinkage attribute affects how the function’s arguments are passed. <!--l. 1228--><p class="noindent" >When you’re in a return probe, <span class="tctt-1000">$</span><span class="cmtt-10">return </span>isn’t supported without DWARF, but you can call <span class="cmtt-10">returnval() </span>to get the value of the register in which the function value is typically returned, or call <span class="cmtt-10">returnstr() </span>to get a string version of that value. <!--l. 1233--><p class="noindent" >And at any code probepoint, you can call <span class="cmtt-10">register("regname") </span>to get the value of the specified CPU register when the probe point was hit. <span class="cmtt-10">u</span><span class="cmtt-10">_register("regname") </span>is like <span class="cmtt-10">register("regname")</span>, but interprets the value as an unsigned integer. <!--l. 1239--><p class="noindent" >SystemTap supports the following constructs: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1240--><p class="indent" > <pre class="verbatim" id="verbatim-43"> kprobe.function(FUNCTION) kprobe.function(FUNCTION).return kprobe.module(NAME).function(FUNCTION) kprobe.module(NAME).function(FUNCTION).return kprobe.statement(ADDRESS).absolute </pre> <!--l. 1247--><p class="nopar" ></dd></dl> <!--l. 1250--><p class="noindent" >Use <span class="cmbx-10">.function </span>probes for kernel functions and <span class="cmbx-10">.module </span>probes for probing functions of a specified module. If you do not know the absolute address of a kernel or module function, use <span class="cmbx-10">.statement </span>probes. Do not use wildcards in <span class="cmti-10">FUNCTION </span>and <span class="cmti-10">MODULE </span>names. Wildcards cause the probe to not register. Also, statement probes are available only in guru mode. <!--l. 1258--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.5 </span> <a id="x6-420004.5"></a>Userspace probing</h4> <a id="dx6-42001"></a> <a id="dx6-42002"></a> <!--l. 1261--><p class="noindent" >Support for userspace probing is supported on kernels that are configured to include the utrace or uprobes extensions. <!--l. 1264--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.5.1 </span> <a id="x6-430004.5.1"></a>Begin/end variants</h5> <!--l. 1266--><p class="noindent" >Constructs: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1267--><p class="indent" > <pre class="verbatim" id="verbatim-44"> process.begin process("PATH").begin process(PID).begin process.thread.begin process("PATH").thread.begin process(PID).thread.begin process.end process("PATH").end process(PID).end process.thread.end process("PATH").thread.end process(PID).thread.end </pre> <!--l. 1284--><p class="nopar" ></dd></dl> <!--l. 1287--><p class="noindent" >The <span class="cmtt-10">.begin </span>variant is called when a new process described by <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>is created. If no <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>argument is specified (for example <span class="cmtt-10">process.begin</span>), the probe flags any new process being spawned. <!--l. 1293--><p class="noindent" >The <span class="cmtt-10">.thread.begin </span>variant is called when a new thread described by <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>is created. <!--l. 1296--><p class="noindent" >The <span class="cmtt-10">.end </span>variant is called when a process described by <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>dies. <!--l. 1299--><p class="noindent" >The <span class="cmtt-10">.thread.end </span>variant is called when a thread described by <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>dies. <!--l. 1302--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.5.2 </span> <a id="x6-440004.5.2"></a>Syscall variants</h5> <!--l. 1304--><p class="noindent" >Constructs: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1305--><p class="indent" > <pre class="verbatim" id="verbatim-45"> process.syscall process("PATH").syscall process(PID).syscall process.syscall.return process("PATH").syscall.return process(PID).syscall.return </pre> <!--l. 1314--><p class="nopar" ></dd></dl> <!--l. 1317--><p class="noindent" >The <span class="cmtt-10">.syscall </span>variant is called when a thread described by <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>makes a system call. The system call number is available in the <span class="tctt-1000">$</span><span class="cmtt-10">syscall </span>context variable. The first six arguments of the system call are available in the <span class="tctt-1000">$</span><span class="cmtt-10">argN </span>parameter, for example <span class="tctt-1000">$</span><span class="cmtt-10">arg1</span>, <span class="tctt-1000">$</span><span class="cmtt-10">arg2</span>, and so on. <!--l. 1324--><p class="noindent" >The <span class="cmtt-10">.syscall.return </span>variant is called when a thread described by <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>returns from a system call. The system call number is available in the <span class="tctt-1000">$</span><span class="cmtt-10">syscall </span>context variable. The return value of the system call is available in the <span class="tctt-1000">$</span><span class="cmtt-10">return </span>context variable. <!--l. 1331--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.5.3 </span> <a id="x6-450004.5.3"></a>Function/statement variants</h5> <!--l. 1333--><p class="noindent" >Constructs: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1334--><p class="indent" > <pre class="verbatim" id="verbatim-46"> process("PATH").function("NAME") process("PATH").statement("*@FILE.c:123") process("PATH").function("*").return process("PATH").function("myfun").label("foo") </pre> <!--l. 1340--><p class="nopar" ></dd></dl> <!--l. 1343--><p class="noindent" >Full symbolic source-level probes in userspace programs and shared libraries are supported. These are exactly analogous to the symbolic DWARF-based kernel or module probes described previously and expose similar contextual <span class="tctt-1000">$</span><span class="cmtt-10">-variables</span>. See Section <a href="#x6-370004.2">4.2<!--tex4ht:ref: dwarfprobes --></a> for more information <!--l. 1349--><p class="noindent" >Here is an example of prototype symbolic userspace probing support: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1350--><p class="indent" > <pre class="verbatim" id="verbatim-47"> # stap -e ’probe process("ls").function("*").call {            log (probefunc()." ".$$parms)            }’ \        -c ’ls -l’ </pre> <!--l. 1356--><p class="nopar" ></dd></dl> <!--l. 1359--><p class="noindent" >To run, this script requires debugging information for the named program and utrace support in the kernel. If you see a ”pass 4a-time” build failure, check that your kernel supports utrace. <!--l. 1363--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.5.4 </span> <a id="x6-460004.5.4"></a>Absolute variant</h5> <!--l. 1365--><p class="noindent" >A non-symbolic probe point such as <span class="cmtt-10">process(PID).statement(ADDRESS).absolute </span>is analogous to <br class="newline" /><span class="cmtt-10">kernel.statement(ADDRESS).absolute </span>in that both use raw, unverified virtual addresses and provide no <span class="tctt-1000">$</span><span class="cmtt-10">variables</span>. The target <span class="cmtt-10">PID </span>parameter must identify a running process and <span class="cmtt-10">ADDRESS </span>must identify a valid instruction address. All threads of the listed process will be probed. This is a guru mode probe. <!--l. 1374--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.5.5 </span> <a id="x6-470004.5.5"></a>Process probe paths</h5> <!--l. 1376--><p class="noindent" >For all process probes, <span class="cmtt-10">PATH </span>names refer to executables that are searched the same way that shells do: the explicit path specified if the path name begins with a slash (/) character sequence; otherwise <span class="tctt-1000">$</span><span class="cmtt-10">PATH </span>is searched. For example, the following probe syntax: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1380--><p class="indent" > <pre class="verbatim" id="verbatim-48"> probe process("ls").syscall {} probe process("./a.out").syscall {} </pre> <!--l. 1384--><p class="nopar" ></dd></dl> <!--l. 1387--><p class="noindent" >works the same as: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1388--><p class="indent" > <pre class="verbatim" id="verbatim-49"> probe process("/bin/ls").syscall {} probe process("/my/directory/a.out").syscall {} </pre> <!--l. 1392--><p class="nopar" ></dd></dl> <!--l. 1395--><p class="noindent" >If a process probe is specified without a <span class="cmtt-10">PID </span>or <span class="cmtt-10">PATH </span>parameter, all user threads are probed. However, if systemtap is invoked in target process mode, process probes are restricted to the process hierarchy associated with the target process. If stap is running in <span class="cmtt-10">--unprivileged </span>mode, only processes owned by the current user are selected. <!--l. 1402--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.5.6 </span> <a id="x6-480004.5.6"></a>Target process mode</h5> <!--l. 1404--><p class="noindent" >Target process mode (invoked with <span class="cmtt-10">stap -c CMD </span>or <span class="cmtt-10">-x PID</span>) implicitly restricts all <span class="cmtt-10">process.* </span>probes to the given child process. It does not affect <span class="cmtt-10">kernel.* </span>or other probe types. The <span class="cmtt-10">CMD </span>string is normally run directly, rather than from a “<span class="cmtt-10">/bin/sh -c</span>” sub-shell, since utrace and uprobe probes receive a fairly ”clean” event stream. If meta-characters such as redirection operators are present in <span class="cmtt-10">CMD</span>, “<span class="cmtt-10">/bin/sh -c CMD</span>” is still used, and utrace and uprobe probes will receive events from the shell. For example: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1413--><p class="indent" > <pre class="verbatim" id="verbatim-50"> % stap -e ’probe process.syscall, process.end {            printf("%s %d %s\n", execname(), pid(), pp())}’ \        -c ls </pre> <!--l. 1418--><p class="nopar" ></dd></dl> <!--l. 1421--><p class="noindent" >Here is the output from this command: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1422--><p class="indent" > <pre class="verbatim" id="verbatim-51"> ls 2323 process.syscall ls 2323 process.syscall ls 2323 process.end </pre> <!--l. 1427--><p class="nopar" ></dd></dl> <!--l. 1430--><p class="noindent" >If <span class="cmtt-10">PATH </span>names a shared library, all processes that map that shared library can be probed. If dwarf debugging information is installed, try using a command with this syntax: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1433--><p class="indent" > <pre class="verbatim" id="verbatim-52"> probe process("/lib64/libc-2.8.so").function("....") { ... } </pre> <!--l. 1436--><p class="nopar" ></dd></dl> <!--l. 1438--><p class="noindent" >This command probes all threads that call into that library. Typing “<span class="cmtt-10">stap -c CMD</span>” or “<span class="cmtt-10">stap -x PID</span>” restricts this to the target command and descendants only. You can use <span class="tctt-1000">$$</span><span class="cmtt-10">vars </span>and others. You can provide the location of debug information to the stap command with the <span class="cmtt-10">-d DIRECTORY </span>option. To qualify a probe point to a location in a library required by a particular process try using a command with this syntax: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1445--><p class="indent" > <pre class="verbatim" id="verbatim-53"> probe process("...").library("...").function("....") { ... } </pre> <!--l. 1448--><p class="nopar" ></dd></dl> <!--l. 1450--><p class="noindent" >The library name may use wildcards. <!--l. 1452--><p class="noindent" >The first syntax in the following will probe the functions in the program linkage table of a particular process. The second syntax will also add the program linkage tables of libraries required by that process. .plt(”...”) can be specified to match particular plt entries. <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1456--><p class="indent" > <pre class="verbatim" id="verbatim-54"> probe process("...").plt { ... } probe process("...").plt process("...").library("...").plt { ... } </pre> <!--l. 1460--><p class="nopar" ></dd></dl> <!--l. 1463--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.5.7 </span> <a id="x6-490004.5.7"></a>Static userspace probing</h5> <!--l. 1465--><p class="noindent" >You can probe symbolic static instrumentation compiled into programs and shared libraries with the following syntax: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1467--><p class="indent" > <pre class="verbatim" id="verbatim-55"> process("PATH").mark("LABEL") </pre> <!--l. 1470--><p class="nopar" ></dd></dl> <!--l. 1473--><p class="noindent" >The <span class="cmtt-10">.mark </span>variant is called from a static probe defined in the application by <span class="cmtt-10">STAP</span><span class="cmtt-10">_PROBE1(handle,LABEL,arg1)</span>. <span class="cmtt-10">STAP</span><span class="cmtt-10">_PROBE1 </span>is defined in the sdt.h file. The parameters are: <div class="tabular"> <table id="TBL-2" class="tabular" ><colgroup id="TBL-2-1g"><col id="TBL-2-1"></colgroup><colgroup id="TBL-2-2g"><col id="TBL-2-2"></colgroup><colgroup id="TBL-2-3g"><col id="TBL-2-3"></colgroup><tr style="vertical-align:baseline;" id="TBL-2-1-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-1-1" class="td11"> Parameter </td><td style="white-space:nowrap; text-align:right;" id="TBL-2-1-2" class="td11"> Definition </td></tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-2-2-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-2-1" class="td11"> <span class="cmtt-10">handle </span></td><td style="white-space:nowrap; text-align:right;" id="TBL-2-2-2" class="td11"> the application handle</td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-2-3-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-3-1" class="td11"> <span class="cmtt-10">LABEL </span></td><td style="white-space:nowrap; text-align:right;" id="TBL-2-3-2" class="td11"> corresponds to the <span class="cmtt-10">.mark </span>argument </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-2-4-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-4-1" class="td11"> <span class="cmtt-10">arg1 </span></td><td style="white-space:nowrap; text-align:right;" id="TBL-2-4-2" class="td11"> the argument </td> </tr><tr class="hline"><td><hr></td><td><hr></td><td><hr></td></tr><tr style="vertical-align:baseline;" id="TBL-2-5-"><td style="white-space:nowrap; text-align:left;" id="TBL-2-5-1" class="td11"> </td> </tr></table> </div> <!--l. 1487--><p class="noindent" >Use <span class="cmtt-10">STAP</span><span class="cmtt-10">_PROBE1 </span>for probes with one argument. Use <span class="cmtt-10">STAP</span><span class="cmtt-10">_PROBE2 </span>for probes with 2 arguments, and so on. The arguments of the probe are available in the context variables <span class="tctt-1000">$</span><span class="cmtt-10">arg1</span>, <span class="tctt-1000">$</span><span class="cmtt-10">arg2</span>, and so on. <!--l. 1492--><p class="noindent" >As an alternative to the <span class="cmtt-10">STAP</span><span class="cmtt-10">_PROBE </span>macros, you can use the dtrace script to create custom macros. The sdt.h file also provides dtrace compatible markers through <span class="cmtt-10">DTRACE</span><span class="cmtt-10">_PROBE </span>and an associated python <span class="cmtt-10">dtrace </span>script. You can use these in builds based on dtrace that need dtrace -h or -G functionality. <!--l. 1498--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.6 </span> <a id="x6-500004.6"></a>Java probes</h4> <a id="dx6-50001"></a> <!--l. 1500--><p class="noindent" >Support for probing Java methods is available using Byteman as a backend. Byteman is an instrumentation tool from the JBoss project which systemtap can use to monitor invocations for a specific method or line in a Java program. <!--l. 1505--><p class="noindent" >Systemtap does so by generating a Byteman script listing the probes to instrument and then invoking the Byteman <span class="cmtt-10">bminstall </span>utility. A custom option <span class="cmtt-10">-D OPTION </span>(see the Byteman documentation for more details) can be passed to bminstall by invoking systemtap with option <span class="cmtt-10">-J OPTION</span>. The systemtap option <span class="cmtt-10">-j </span>is also provided as a shorthand for <span class="cmtt-10">-J org.jboss.byteman.compile.to.bytecode</span>. <!--l. 1513--><p class="noindent" >This Java instrumentation support is currently a prototype feature with major limitations: Java probes attach only to one Java process at a time; other Java processes beyond the first one to be observed are ignored. Moreover, Java probing currently does not work across users; the stap script must run (with appropriate permissions) under the same user as the Java process being probed. (Thus a stap script under root currently cannot probe Java methods in a non-root-user Java process.) <!--l. 1521--><p class="noindent" >There are four probe point variants supported by the translator: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1522--><p class="indent" > <pre class="verbatim" id="verbatim-56"> java("PNAME").class("CLASSNAME").method("PATTERN") java("PNAME").class("CLASSNAME").method("PATTERN").return java(PID).class("CLASSNAME").method("PATTERN") java(PID).class("CLASSNAME").method("PATTERN").return </pre> <!--l. 1528--><p class="nopar" ></dd></dl> <!--l. 1531--><p class="noindent" >The first two probe points refer to Java processes by the name of the Java process. The PATTERN parameter specifies the signature of the Java method to probe. The signature must consist of the exact name of the method, followed by a bracketed list of the types of the arguments, for instance <span class="cmtt-10">myMethod(int,double,Foo)</span>. Wildcards are not supported. <!--l. 1538--><p class="noindent" >The probe can be set to trigger at a specific line within the method by appending a line number with colon, just as in other types of probes: <span class="cmtt-10">myMethod(int,double,Foo):245</span>. <!--l. 1542--><p class="noindent" >The CLASSNAME parameter identifies the Java class the method belongs to, either with or without the package qualification. By default, the probe only triggers on descendants of the class that do not override the method definition of the original class. However, CLASSNAME can take an optional caret prefix, as in <span class="obeylines-h"><span class="verb"><span class="cmtt-10">class("^org.my.MyClass")</span></span></span>, which specifies that the probe should also trigger on all descendants of MyClass that override the original method. For instance, every method with signature foo(int) in program org.my.MyApp can be probed at once using <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1551--><p class="indent" > <pre class="verbatim" id="verbatim-57"> java("org.my.MyApp").class("^java.lang.Object").method("foo(int)") </pre> <!--l. 1554--><p class="nopar" ></dd></dl> <!--l. 1557--><p class="noindent" >The last two probe points work analogously, but refer to Java processes by PID. (PIDs for already running processes can be obtained using the <span class="cmtt-10">jps </span>utility.) <!--l. 1561--><p class="noindent" >Context variables defined within java probes include <span class="obeylines-h"><span class="verb"><span class="cmtt-10">$provider</span></span></span> (which identifies the class providing the definition of the triggered method) and <span class="obeylines-h"><span class="verb"><span class="cmtt-10">$name</span></span></span> (which gives the signature of the method). Arguments to the method can be accessed using context variables <span class="obeylines-h"><span class="verb"><span class="cmtt-10">$arg1$</span></span></span> through <span class="obeylines-h"><span class="verb"><span class="cmtt-10">$arg10</span></span></span>, for up to the first 10 arguments of a method. <!--l. 1568--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.7 </span> <a id="x6-510004.7"></a>PROCFS probes</h4> <a id="dx6-51001"></a> <!--l. 1570--><p class="noindent" >These probe points allow procfs pseudo-files in <span class="cmtt-10">/proc/systemtap/</span><span class="cmitt-10">MODNAME </span>to be created, read and written. Specify the name of the systemtap module as <span class="cmitt-10">MODNAME </span>. There are four probe point variants supported by the translator: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1575--><p class="indent" > <pre class="verbatim" id="verbatim-58"> procfs("PATH").read procfs("PATH").write procfs.read procfs.write </pre> <!--l. 1581--><p class="nopar" ></dd></dl> <!--l. 1584--><p class="noindent" ><span class="cmtt-10">PATH </span>is the file name to be created, relative to <span class="cmtt-10">/proc/systemtap/MODNAME</span>. If no <span class="cmtt-10">PATH </span>is specified (as in the last two variants in the previous list), <span class="cmtt-10">PATH </span>defaults to ”command”. <!--l. 1589--><p class="noindent" >When a user reads <span class="cmtt-10">/proc/systemtap/MODNAME/PATH</span>, the corresponding procfs read probe is triggered. Assign the string data to be read to a variable named <span class="tctt-1000">$</span><span class="cmtt-10">value</span>, as follows: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1592--><p class="indent" > <pre class="verbatim" id="verbatim-59"> procfs("PATH").read { $value = "100\n" } </pre> <!--l. 1595--><p class="nopar" ></dd></dl> <!--l. 1598--><p class="noindent" >When a user writes into <span class="cmtt-10">/proc/systemtap/MODNAME/PATH</span>, the corresponding procfs write probe is triggered. The data the user wrote is available in the string variable named <span class="tctt-1000">$</span><span class="cmtt-10">value</span>, as follows: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1602--><p class="indent" > <pre class="verbatim" id="verbatim-60"> procfs("PATH").write { printf("User wrote: %s", $value) } </pre> <!--l. 1605--><p class="nopar" ></dd></dl> <!--l. 1609--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.8 </span> <a id="x6-520004.8"></a>Marker probes</h4> <a id="dx6-52001"></a> <!--l. 1611--><p class="noindent" >This family of probe points connects to static probe markers inserted into the kernel or a module. These markers are special macro calls in the kernel that make probing faster and more reliable than with DWARF-based probes. DWARF debugging information is not required to use probe markers. <!--l. 1617--><p class="noindent" >Marker probe points begin with a <span class="cmtt-10">kernel </span>prefix which identifies the source of the symbol table used for finding markers. The suffix names the marker itself: <span class="cmtt-10">mark.("MARK")</span>. The marker name string, which can contain wildcard characters, is matched against the names given to the marker macros when the kernel or module is compiled. Optionally, you can specify <span class="cmtt-10">format("FORMAT")</span>. Specifying the marker format string allows differentiation between two markers with the same name but different marker format strings. <!--l. 1627--><p class="noindent" >The handler associated with a marker probe reads any optional parameters specified at the macro call site named <span class="tctt-1000">$</span><span class="cmtt-10">arg1 </span>through <span class="tctt-1000">$</span><span class="cmtt-10">argNN</span>, where <span class="cmtt-10">NN </span>is the number of parameters supplied by the macro. Number and string parameters are passed in a type-safe manner. <!--l. 1633--><p class="noindent" >The marker format string associated with a marker is available in <span class="tctt-1000">$</span><span class="cmtt-10">format</span>. The marker name string is available in <span class="tctt-1000">$</span><span class="cmtt-10">name</span>. <!--l. 1637--><p class="noindent" >Here are the marker probe constructs: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1638--><p class="indent" > <pre class="verbatim" id="verbatim-61"> kernel.mark("MARK") kernel.mark("MARK").format("FORMAT") </pre> <!--l. 1642--><p class="nopar" ></dd></dl> <!--l. 1645--><p class="noindent" >For more information about marker probes, see <a href="http://sourceware.org/systemtap/wiki/UsingMarkers" class="url" ><span class="cmtt-10">http://sourceware.org/systemtap/wiki/UsingMarkers</span></a>. <!--l. 1649--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.9 </span> <a id="x6-530004.9"></a>Tracepoints</h4> <a id="dx6-53001"></a> <!--l. 1653--><p class="noindent" >This family of probe points hooks to static probing tracepoints inserted into the kernel or kernel modules. As with marker probes, these tracepoints are special macro calls inserted by kernel developers to make probing faster and more reliable than with DWARF-based probes. DWARF debugging information is not required to probe tracepoints. Tracepoints have more strongly-typed parameters than marker probes. <!--l. 1661--><p class="noindent" >Tracepoint probes begin with <span class="cmtt-10">kernel</span>. The next part names the tracepoint itself: <span class="cmtt-10">trace("name")</span>. The tracepoint <span class="cmtt-10">name </span>string, which can contain wildcard characters, is matched against the names defined by the kernel developers in the tracepoint header files. <!--l. 1667--><p class="noindent" >The handler associated with a tracepoint-based probe can read the optional parameters specified at the macro call site. These parameters are named according to the declaration by the tracepoint author. For example, the tracepoint probe <span class="cmtt-10">kernel.trace("sched</span><span class="cmtt-10">_switch") </span>provides the parameters <span class="tctt-1000">$</span><span class="cmtt-10">rq</span>, <span class="tctt-1000">$</span><span class="cmtt-10">prev</span>, and <span class="tctt-1000">$</span><span class="cmtt-10">next</span>. If the parameter is a complex type such as a struct pointer, then a script can access fields with the same syntax as DWARF <span class="tctt-1000">$</span><span class="cmtt-10">target</span> variables. Tracepoint parameters cannot be modified; however, in guru mode a script can modify fields of parameters. <!--l. 1678--><p class="noindent" >The name of the tracepoint is available in <span class="tctt-1000">$$</span><span class="cmtt-10">name</span>, and a string of <span class="cmtt-10">name=value </span>pairs for all parameters of the tracepoint is available in <span class="tctt-1000">$$</span><span class="cmtt-10">vars </span>or <span class="tctt-1000">$$</span><span class="cmtt-10">parms</span>. <!--l. 1683--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.10 </span> <a id="x6-540004.10"></a>Syscall probes</h4> <a id="dx6-54001"></a> <!--l. 1686--><p class="noindent" >The <span class="cmtt-10">syscall.* </span>aliases define several hundred probes. They use the following syntax: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1688--><p class="indent" > <pre class="verbatim" id="verbatim-62"> syscall.NAME syscall.NAME.return </pre> <!--l. 1692--><p class="nopar" ></dd></dl> <!--l. 1695--><p class="noindent" >Generally, two probes are defined for each normal system call as listed in the syscalls(2) manual page: one for entry and one for return. System calls that never return do not have a corresponding <span class="cmtt-10">.return</span> probe. <!--l. 1700--><p class="noindent" >Each probe alias defines a variety of variables. Look at the tapset source code to find the most reliable source of variable definitions. Generally, each variable listed in the standard manual page is available as a script-level variable. For example, <span class="cmtt-10">syscall.open </span>exposes file name, flags, and mode. In addition, a standard suite of variables is available at most aliases, as follows: <ul class="itemize1"> <li class="itemize"> <!--l. 1708--><p class="noindent" ><span class="cmtt-10">argstr</span>: A pretty-printed form of the entire argument list, without parentheses. </li> <li class="itemize"> <!--l. 1710--><p class="noindent" ><span class="cmtt-10">name</span>: The name of the system call. </li> <li class="itemize"> <!--l. 1711--><p class="noindent" ><span class="cmtt-10">retstr</span>: For return probes, a pretty-printed form of the system call result.</li></ul> <!--l. 1715--><p class="noindent" >Not all probe aliases obey all of these general guidelines. Please report exceptions that you encounter as a bug. <!--l. 1719--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.11 </span> <a id="x6-550004.11"></a>Timer probes</h4> <a id="dx6-55001"></a> <!--l. 1721--><p class="noindent" >You can use intervals defined by the standard kernel jiffies<a id="dx6-55002"></a> timer to trigger probe handlers asynchronously. A <span class="cmti-10">jiffy </span>is a kernel-defined unit of time typically between 1 and 60 msec. Two probe point variants are supported by the translator: <!--l. 1726--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1726--><p class="indent" > <pre class="verbatim" id="verbatim-63"> timer.jiffies(N) timer.jiffies(N).randomize(M) </pre> <!--l. 1730--><p class="nopar" ></dd></dl> <!--l. 1732--><p class="noindent" >The probe handler runs every N jiffies. If the <span class="cmtt-10">randomize</span><a id="dx6-55003"></a> component is given, a linearly distributed random value in the range [-M … +M] is added to N every time the handler executes. N is restricted to a reasonable range (1 to approximately 1,000,000), and M is restricted to be less than N. There are no target variables provided in either context. Probes can be run concurrently on multiple processors. <!--l. 1739--><p class="noindent" >Intervals may be specified in units of time. There are two probe point variants similar to the jiffies timer: <!--l. 1742--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1742--><p class="indent" > <pre class="verbatim" id="verbatim-64"> timer.ms(N) timer.ms(N).randomize(M) </pre> <!--l. 1746--><p class="nopar" ></dd></dl> <!--l. 1748--><p class="noindent" >Here, N and M are specified in milliseconds<a id="dx6-55004"></a>, but the full options for units are seconds (s or sec), milliseconds (ms or msec), microseconds (us or usec), nanoseconds (ns or nsec), and hertz (hz). Randomization is not supported for hertz timers. <!--l. 1753--><p class="noindent" >The resolution of the timers depends on the target kernel. For kernels prior to 2.6.17, timers are limited to jiffies resolution, so intervals are rounded up to the nearest jiffies interval. After 2.6.17, the implementation uses hrtimers for greater precision, though the resulting resolution will be dependent upon architecture. In either case, if the randomize component is given, then the random value will be added to the interval before any rounding occurs. <!--l. 1760--><p class="noindent" >Profiling timers are available to provide probes that execute on all CPUs at each system tick. This probe takes no parameters, as follows. <!--l. 1763--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1763--><p class="indent" > <pre class="verbatim" id="verbatim-65"> timer.profile.tick </pre> <!--l. 1766--><p class="nopar" ></dd></dl> <!--l. 1768--><p class="noindent" >Full context information of the interrupted process is available, making this probe suitable for implementing a time-based sampling profiler. <!--l. 1771--><p class="noindent" >It is recommended to use the tapset probe <span class="obeylines-h"><span class="verb"><span class="cmtt-10">timer.profile</span></span></span> rather than <span class="obeylines-h"><span class="verb"><span class="cmtt-10">timer.profile.tick</span></span></span>. This probe point behaves identically to <span class="obeylines-h"><span class="verb"><span class="cmtt-10">timer.profile.tick</span></span></span> when the underlying functionality is available, and falls back to using <span class="obeylines-h"><span class="verb"><span class="cmtt-10">perf.sw.cpu_clock</span></span></span> on some recent kernels which lack the corresponding profile timer facility. <!--l. 1777--><p class="noindent" >The following is an example of timer usage. <!--l. 1779--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1779--><p class="indent" > <pre class="verbatim" id="verbatim-66"> # Refers to a periodic interrupt, every 1000 jiffies: timer.jiffies(1000) # Fires every 5 seconds: timer.sec(5) # Refers to a periodic interrupt, every 1000 +/- 200 jiffies: timer.jiffies(1000).randomize(200) </pre> <!--l. 1789--><p class="nopar" ></dd></dl> <!--l. 1792--><p class="noindent" > <h4 class="subsectionHead"><span class="titlemark">4.12 </span> <a id="x6-560004.12"></a>Special probe points</h4> <!--l. 1794--><p class="noindent" >The probe points <span class="cmtt-10">begin </span>and <span class="cmtt-10">end </span>are defined by the translator to refer to the time of session startup and shutdown. There are no target variables available in either context. <!--l. 1799--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.12.1 </span> <a id="x6-570004.12.1"></a>begin</h5> <a id="dx6-57001"></a> <!--l. 1801--><p class="noindent" >The <span class="cmtt-10">begin </span>probe is the start of the SystemTap session. All <span class="cmtt-10">begin </span>probe handlers are run during the startup of the session. <!--l. 1806--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.12.2 </span> <a id="x6-580004.12.2"></a>end</h5> <a id="dx6-58001"></a> <!--l. 1808--><p class="noindent" >The <span class="cmtt-10">end </span>probe is the end of the SystemTap session. All <span class="cmtt-10">end </span>probes are run during the normal shutdown of a session, such as in the aftermath of a SystemTap <span class="cmtt-10">exit </span>function call, or an interruption from the user. In the case of an shutdown triggered by error, <span class="cmtt-10">end </span>probes are not run. <!--l. 1814--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.12.3 </span> <a id="x6-590004.12.3"></a>error</h5> <a id="dx6-59001"></a> <!--l. 1816--><p class="noindent" >The <span class="cmti-10">error </span>probe point is similar to the end probe, except the probe handler runs when the session ends if an error occurred. In this case, an <span class="cmtt-10">end </span>probe is skipped, but each <span class="cmtt-10">error </span>probe is still attempted. You can use an <span class="cmtt-10">error </span>probe to clean up or perform a final action on script termination. <!--l. 1823--><p class="noindent" >Here is a simple example: <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1824--><p class="indent" > <pre class="verbatim" id="verbatim-67"> probe error { println ("Oops, errors occurred. Here’s a report anyway.")               foreach (coin in mint) { println (coin) } } </pre> <!--l. 1828--><p class="nopar" ></dd></dl> <!--l. 1832--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.12.4 </span> <a id="x6-600004.12.4"></a>begin, end, and error probe sequence</h5> <a id="dx6-60001"></a> <!--l. 1834--><p class="noindent" ><span class="cmtt-10">begin</span>, <span class="cmtt-10">end</span>, and <span class="cmtt-10">error </span>probes can be specified with an optional sequence number that controls the order in which they are run. If no sequence number is provided, the sequence number defaults to zero and probes are run in the order that they occur in the script file. Sequence numbers may be either positive or negative, and are especially useful for tapset writers who want to do initialization in a <span class="cmtt-10">begin </span>probe. The following are examples. <!--l. 1842--><p class="noindent" > <dl class="list1"><dt class="list"> </dt><dd class="list"> <!--l. 1842--><p class="indent" > <pre class="verbatim" id="verbatim-68"> # In a tapset file: probe begin(-1000) { ... } # In a user script: probe begin { ... } </pre> <!--l. 1849--><p class="nopar" ></dd></dl> <!--l. 1851--><p class="noindent" >The user script <span class="cmtt-10">begin </span>probe defaults to sequence number zero, so the tapset <span class="cmtt-10">begin </span>probe will run first. <!--l. 1855--><p class="noindent" > <h5 class="subsubsectionHead"><span class="titlemark">4.12.5 </span> <a id="x6-610004.12.5"></a>never</h5> <a id="dx6-61001"></a> <!--l. 1857--><p class="noindent" >The <span class="cmtt-10">never </span>probe point is defined by the translator to mean <span class="cmti-10">never</span>. Its statements are analyzed for symbol and type correctness, but its probe handler is never run. This probe point may be useful in conjunction with optional probes. See Section <a href="#x6-350004.1.4">4.1.4<!--tex4ht:ref: sub:Optional-probe-points --></a>. <!--l. 1863--><div class="crosslinks"><p class="noindent">[<a href="langrefse5.html" >next</a>] [<a href="langrefse3.html" >prev</a>] [<a href="langrefse3.html#taillangrefse3.html" >prev-tail</a>] [<a href="langrefse4.html" >front</a>] [<a href="langref.html#langrefse4.html" >up</a>] </p></div> <!--l. 1863--><p class="noindent" ><a id="taillangrefse4.html"></a> </body></html>
|
