Debian Codegraph @

man/cs/stap.1.in

raw
1 .\" -*- nroff -*-
2 .TH STAP 1
3 .SH JMÉNO
4 stap \- překladač a řadič systemtap skriptů
5
6 .\" macros
7 .\" do not nest SAMPLEs
8 .de SAMPLE
9 .br
10
11 .nr oldin \\n(.i
12 .RS
13 .nf
14 .nh
15 ..
16 .de ESAMPLE
17 .hy
18 .fi
19 .RE
20 .in \\n[oldin]u
21
22 ..
23
24 .SH POUŽITÍ
25
26 .br
27 .B stap
28 [
29 .I VOLBY
30 ]
31 .I JMÉNO_SOUBORU
32 [
33 .I ARGUMENTY
34 ]
35 .br
36 .B stap
37 [
38 .I VOLBY
39 ]
40 .B \-
41 [
42 .I ARGUMENTY
43 ]
44 .br
45 .B stap
46 [
47 .I VOLBY
48 ]
49 .BI \-e " SKRIPT"
50 [
51 .I ARGUMENTY
52 ]
53 .br
54 .B stap
55 [
56 .I VOLBY
57 ]
58 .BI \-l " PROBE"
59 [
60 .I ARGUMENTY
61 ]
62 .br
63 .B stap
64 [
65 .I VOLBY
66 ]
67 .BI \-L " PROBE"
68 [
69 .I ARGUMENTY
70 ]
71 .br
72 .B stap
73 [
74 .I VOLBY
75 ]
76 .B \-\-dump-probe-types
77 .br
78 .B stap
79 [
80 .I VOLBY
81 ]
82 .B \-\-dump-probe-aliases
83 .br
84 .B stap
85 [
86 .I VOLBY
87 ]
88 .B \-\-dump-functions
89
90
91 .SH POPIS
92
93 Program
94 .IR stap
95 je hlavním uživatelským rozhraním nástroje systemtap. Přijímá požadavky na
96 sondování systému (probing) zapsané v jednoduchém skriptovacím jazyce, překládá
97 je do jazyka C, výsledný kód zkompiluje a vytvoří jaderný modul, který následně
98 zavede do běžícího linuxového jádra nebo dyninst instrumentačního nástroje, aby
99 prováděl požadovanou analýzu zkoumaného systému. Skript může být čten ze
100 souboru (JMÉNO_SOUBORU), ze standardního vstupu (v tom případě použijte "\-"
101 namísto JMÉNO_SOUBORU), z příkazové řádky (prostřednictvím přepínače -e SKRIPT,
102 případně -E SKRIPT). Program běží dokud není přerušen uživatelem, nebo dokud
103 skript nezavolá
104 .I exit(),
105 nebo dokud nedojde k nastřádání dostatečného množství tzv. měkkých chyb (soft
106 errors).
107
108 .PP
109 Jazyk, který je popsán níže v sekci
110 .IR "SKRIPTOVACÍ JAZYK" ,
111 je striktně typovaný, imperativní, bez explicitních deklarací, procedurální,
112 vhodný k prototypování a inspirovaný
113 .IR awk " a " C .
114 Umožňuje spojit místo ve zdrojovém kódu linuxového jádra, nebo uživatelské
115 aplikace, případně systémovou událost s obslužnými rutinami, což jsou bloky
116 kódu vykonávané synchronně. Koncepčně to připomíná skriptování v
117 .IR gdb .
118
119 .SH "PŘEHLED DOKUMENTACE"
120
121 Pro SystemTap existuje množství vzdělávacích, dokumentačních a referenčních
122 materiálů jak v online podobě, tak i v rámci distribučních balíčků. Online
123 dokumentace se nachází na projektovém webu
124 .nh
125 https://sourceware.org/systemtap/
126 .hy
127 .
128
129 .TS
130 tab(%) allbox;
131 l l.
132 \fBman stránky\fP
133 stap (tato stránka)%syntaxe jazyka, koncepty, funkce, volby
134 stapprobes%sondážní body a jejich kontextové proměnné
135 stapref%rychlá reference pro syntaxi jazyka
136 stappaths%T{
137 seznam důležitých umístění včetně knih a odkazů
138 T}
139 stap-prep%T{
140 instalátor závislostí jako např. ladicích informací jádra
141 T}
142 tapset::*%vygenerovaný seznam tapsetů
143 probe::*%vygenerovaný seznam tapsetových přezdívek
144 function::*%vygenerovaný seznam tapsetových funkcí
145 macro::*%vygenerovaný seznam tapsetových maker
146 stapvars%vybrané globální proměnné definované v tapsetech
147 staprun, stapdyn, stapbpf%programy pro spuštění zkompilovaných systemtap skriptů
148 systemtap%systémová služba, analýza startu systému
149 stap-server%kompilační server
150 stapex%několik velmi jednoduchých příkladů
151 \fBknihy\fP%
152 Beginner's Guide%učebnice základů s praktickými ukázkami
153 Tutorial%hutný úvod, cvičení
154 Language Reference%podrobný manuál skriptovacího jazyka
155 Tapset Reference%man stránky tapsetů v podobě knihy
156 \fBodkazy\fP%
157 example scripts%T{
158 množství nástrojů pro správu systému, ukázkových skriptů a výukových hraček
159 T}
160 .TE
161
162 .SH VOLBY
163
164 Příkaz
165 .IR stap
166 akceptuje následující volby. Jakákoliv jiná volba vypíše seznam podporovaných
167 voleb. Volby lze uvést na příkazové řádce, jak je obvyklé. Pokud existuje
168 $SYSTEMTAP_DIR/rc, mohou být volby načteny odtud a interpretovány nejdříve.
169 Pokud není $SYSTEMTAP_DIR nastavena, použije se $HOME/.systemtap jako výchozí.
170
171 .PP
172 V některých případech může výchozí hodnota volby záviset na konkrétní konfiguraci
173 systému a proto zde není přímo uvedena. V takovém případě může pomoci
174 "stap \-\-help".
175
176 .TP
177 .B \-
178 Načte skript ze standardního vstupu namísto ze souboru JMÉNO_SOUBORU, pokud
179 ovšem není dáno -e SKRIPT.
180 .TP
181 .B \-h \-\-help
182 Zobrazí nápovědu.
183 .TP
184 .B \-V \-\-version
185 Zobrazí verzi.
186 .TP
187 .BI \-p " NUM"
188 Zastaví po dokončení procesní fáze NUM. Procesní fáze jsou očíslované 1-5
189 (parse, elaborate, translate, compile, run). Viz sekce
190 .B ZPRACOVÁNÍ .
191 .TP
192 .B \-v
193 Zvýší upovídanost pro všechny procesní fáze. Tuto volbu lze opakovat pro zvýšení
194 množství informativního (?) výstupu.
195 .TP
196 .B \-\-vp ABCDE
197 Zvýší upovídanost pro jednotlivé procesní fáze. Například, "\-\-vp\ 002"
198 přidá 2 jednotky upovídanosti procesní fázi 3. Kombinace "\-v\ \-\-vp\ 00004"
199 přidá 1 jednotku upovídanosti všem procesním fázím, a další čtyři jednotky fázi 5.
200 .TP
201 .B \-k
202 Zachová dočasný procesní adresář, který se jinak po dokončení skriptu smaže.
203 To může být užitečné, chceme-li zkoumat vygenerovaný C kód, nebo jej znovu použít
204 pro vytvoření jaderného modulu.
205 .TP
206 .B \-g
207 Guru režim. Umožní použít potenciálně nebezpečné expertní konstrukce, jako
208 například vložený (embedded) C kód v rámci systemtap skriptu.
209 .TP
210 .B \-P
211 Režim prohledávání prologu (prologue-searching). Ekvivalentem je
212 \-\-prologue\-searching=always. Aktivuje heuristiku pro obcházení problémů s
213 nekonzistentními ladicími informacemi pro kontextové proměnné parametrů funkcí.
214 .TP
215 .B \-u
216 Vypne optimalizace jako např. odstraňování nepotřebného kódu (a mnoho dalších)
217 během 2., či 3. procesní fáze (elaboration, translation).
218 .TP
219 .B \-w
220 Potlačí všechny varovné hlášení.
221 .TP
222 .B \-W
223 Zachází s varováními stejně jako s chybami.
224 .TP
225 .BI \-b
226 Tzv. "bulk" režim pro přenos dat z jádra k uživateli. V tomto režimu jsou data
227 pro jednotlivé CPU přenášena odděleně a zapisována do samostatných souborů. Pro
228 jejich případné sloučení lze použít příkaz
229 .IR stap\-merge.
230 .TP
231 .B \-t
232 Sbírá různé časovací informace jako například počet aktivací (probe hits) pro jednotlivé sondy,
233 průměrný čas strávený v jednotlivých sondách, atd.
234 .TP
235 .BI \-s " NUM"
236 Nastaví velikost bufferu pro přenos dat ze systemtap modulu k uživateli na
237 NUM MB. Na víceprocesorovém systému v "bulk" režimu bude mít tuto velikost
238 každý jednotlivý buffer.
239 .TP
240 .BI \-I " DIR"
241 Přidá DIR mezi cesty ve kterých se vyhledávají tapset skripty. Více informací
242 obsahuje popis procesní fáze 2.
243 .TP
244 .BI \-D " NAME=VALUE"
245 Přidá danou direktivu do Makefile systemtap modulu. Toho lze využít například
246 k předefinování různých omezení popsaných níže.
247 .TP
248 .BI \-B " NAME=VALUE"
249 Předá danou direktivu příkazu make při sestavování systemtap modulu. Toho lze
250 využít k přidání nebo změně "kconfig" voleb.
251 .TP
252 .BI \-a " ARCH"
253 Použije režim křížového překladu (cross compilation) pro danou cílovou
254 architekturu. Tato volba vyžaduje přístup ke kompilačnímu serveru a obvykle se
255 používá spolu s volbami
256 .BR "\-B CROSS_COMPILE=arch\-tool\-prefix\-" " a " "\-r /build/tree" .
257 .TP
258 .BI \-\-modinfo " NAME=VALUE"
259 Přidá pár klíč/hodnota ve formě makra MODULE_INFO do vygenerovaného modulu.
260 Toho lze využít k nastavení nebo úpravě různých jaderných kontrol souvisejících
261 s modulem.
262 .TP
263 .BI \-G " NAME=VALUE"
264 Nastavuje hodnotu globální proměnné NAME na VALUE při volání programu staprun.
265 Tak lze nastavit hodnotu skalární globální proměnné skriptu.
266 .TP
267 .BI \-R " DIR"
268 Prohledává DIR na systemtap runtime zdroje. Výchozí hodnotu DIR lze zobrazit
269 např. prostřednictvím "stap \-\-help".
270 .TP
271 .BI \-r " /DIR"
272 Použije daný jaderný "build tree". Lze také nastavit prostřednictvím proměnné
273 prostředí
274 .I SYSTEMTAP_RELEASE .
275 .TP
276 .BI \-r " RELEASE"
277 Určí "release" jádra v rámci "build tree"
278 .BR /lib/modules/RELEASE/build .
279 Lze též nastavit prostřednictvím proměnné prostředí
280 .I SYSTEMTAP_RELEASE .
281 .TP
282 .BI \-m " MODULE"
283 Použije dané jméno pro vygenerovaný jaderný modul namísto obvyklého náhodně
284 vygenerovaného jména. Takto vygenerovaný modul se pak navíc zkopíruje do
285 aktuálního adresáře.
286 .TP
287 .BI \-d " MODULE"
288 Přidá do systemtap modulu ladicí informace o symbolech a informace pro odvíjení
289 zásobníku pro daný MODULE. Tak lze umožnit symbolické tracebacky pro MODULE i
290 když do něj není explicitně vložena sonda.
291 .TP
292 .BI \-\-ldd
293 Přidá do systemtap modulu ladicí informace pro všechny uživatelské
294 spustitelné soubory nebo DSO knihovny, které ldd podezřívá z užitečnosti pro
295 požadovanou analýzu. Totéž bude do systemtap modulu přidáno i pro moduly
296 vyjmenované pomocí přepínačů \-d. Upozornění: \-\-ldd může systemtap modul
297 značně zvětšit.
298
299 .TP
300 .BI \-\-all\-modules
301 Ekvivalent pro "\-dkernel" a "\-d" pro každý z momentálně zavedených modulů.
302 Upozornění: \-\-all\-modules může systemtap modul značně zvětšit.
303 .TP
304 .BI \-o " FILE"
305 Přesměruje výstup do souboru FILE. V bulk režimu se použije pro každou CPU
306 samostatný soubor s prefixem FILE_ (FILE_cpu s \-F) následovaným číslem CPU.
307 Pro FILE je podporován strftime(3) formát.
308 .TP
309 .BI \-c " CMD"
310 Zavede a nastartuje systemtap modul, spustí příkaz CMD, a vše ukončí spolu s
311 CMD. Vedlejším efektem je nastavení target() na pid CMD.
312 .TP
313 .BI \-x " PID"
314 Nastaví target() na PID. Takto lze psát skripty se zaměřením na daný proces. V
315 tomto případě systemtap skript běží bez ohledu na životní cyklus procesu PID.
316 .TP
317 .BI \-e " SKRIPT"
318 Spustí SKRIPT. Příklad: stap -e "probe oneshot { log("hello") }"
319 .TP
320 .BI \-E " SKRIPT"
321 Spustí SKRIPT. Ten běží spolu s hlavním skriptem určeným pomocí -e nebo
322 načteným ze souboru. Tuto volbu lze opakovat pro načtení většího počtu
323 skriptů. Taktéž ji lze použít v kombinaci s \-l/\-L.
324 .TP
325 .BI \-l " PROBE"
326 Namísto obvyklého spuštění systemtap skriptu, tato volba vypíše všechny
327 sondy které odpovídají parametru PROBE. PROBE může obsahovat zástupné symboly
328 a přezdívky, ale ne seznam čárkou oddělených sondážních bodů. Pokud PROBE
329 neodpovídá žádné dostupné sondě, bude výsledkem chyba.
330 .TP
331 .BI \-L " PROBE"
332 Podobá se "\-l", ale navíc vypíše dostupné lokální proměnné.
333 .TP
334 .BI \-F
335 Bez \-o tato volba zavede systemtap modul, spustí sondy a odpojí se od běžícího
336 modulu. V kombinaci s volbou \-o spustí staprun na pozadí jako démon a vypíše
337 jeho pid.
338 .TP
339 .BI \-S " size[,N]"
340 Nastavuje maximální velikost výstupního souboru a případně také počet
341 výstupních souborů. V případě, že dojde k překročení maximální velikosti
342 výstupního souboru
343 .B size
344 , přepne systemtap svůj výstup do dalšího souboru. Pakliže počet výstupních
345 souborů překročí
346 .B N
347 , systemtap odstraní nejstarší výstupní soubor. Druhý z argumentů lze vynechat.
348 .TP
349 .BI \-T " TIMEOUT"
350 Ukončit skript po uplynutí TIMEOUT sekund.
351 .TP
352 .B \-\-skip\-badvars
353 Ignoruje neidentifikovatelné nebo nedostupné kontextové proměnné a, aniž by
354 došlo k chybě, nahradí jejich hodnotu nulou.
355 .TP
356 \fB\-\-prologue\-searching\fR[=\fIWHEN\fR]
357 Režim prologue-searching. Aktivuje heuristiku k vyrovnání se s nekvalitními
358 ladicí informacemi pro kontextové proměnné funkčních parametrů. WHEN může být
359 "never" (nikdy), "always" (vždy), nebo "auto" (tj. zapnuto na základě
360 heuristiky). Když WHEN chybí, předpokládá se "always". Bez explicitní
361 specifikace se předpokládá "auto".
362 .TP
363 .B \-\-suppress\-handler\-errors
364 Zabalí všechny obslužné rutiny do obálky podobné následujícímu kódu:
365 .SAMPLE
366 try { ... } catch { next }
367 .ESAMPLE
368 blok, který způsobuje chyby v době běhu, bude tiše potlačen. Potlačené chyby se
369 nebudou vyhodnocovat proti limitu
370 .BR MAXERRORS .
371 V tomto režimu je taktéž potlačeno testování
372 .BR MAXSKIPPED
373 , takže při běhu skriptu může dojít k libovolnému množství chyb. Celkové počty
374 chyb budou nicméně reportovány při ukončení skriptu.
375
376 .TP
377 .BI \-\-compatible " VERSION"
378 Z uživatelského hlediska se tato volba pokouší napodobit chování systemtapu
379 dané verze a umožnit tak běh starším skriptům. Viz též sekce ZASTARÁVÁNÍ.
380
381 .TP
382 .BI \-\-check\-version
383 Tato volba slouží k ověření, zda aktivní skript obsahuje konstrukce závislé na
384 verzi systemtapu. Viz též sekce ZASTARÁVÁNÍ.
385
386 .TP
387 .BI \-\-clean\-cache
388 Tato volba smaže zastaralé položky v cache adresáři. To se normálně děje po
389 úspěšném ukončení skriptu, ale tato volba vyčistí cache explicitně, a pak ukončí
390 systemtap. Viz sekce CACHE.
391
392 .TP
393 \fB\-\-color\fR[=\fIWHEN\fR], \fB\-\-colour\fR[=\fIWHEN\fR]
394 Tato volba ovládá obarvování výstupu. WHEN může být "never" (nikdy), "always"
395 (vždy), nebo "auto" (zapnuto pokud jde výstup do terminálu). Pokud WHEN chybí,
396 předpokládá se "auto". Barvy lze měnit prostřednictvím proměnné prostředí
397 SYSTEMTAP_COLORS. Formát je následující:
398 .nh
399 \fBklíč1=hodnota1:klíč2=hodnota2:klíč3=hodnota3\fR ...atd.
400 .hy
401 Platné klíče jsou:
402 .nh
403 "error", "warning", "source", "caret", a "token".
404 .hy
405 Hodnotami jsou "Select Graphic Rendition" (SGR) parametry. Viz dokumentace k
406 použitému terminálu. Příklad výchozího nastavení je:
407 .nh
408 \fBerror=01;31:warning=00;33:source=00;34:caret=01:token=01\fR.
409 .hy
410 Pokud SYSTEMTAP_COLORS chybí, použije se výchozí nastavení. Pokud to je prázdné
411 nebo chybné, obarvování se vypne.
412
413 .TP
414 .BI \-\-disable\-cache
415 Tato volba vypne veškeré používání cache. Žádné soubory nebudou do cache
416 adresáře zapsány, ani z něj čteny.
417
418 .TP
419 .BI \-\-poison\-cache
420 Tato volba zachází se soubory v cache jako s neplatnými. Žádné soubory nebudou
421 z cache čteny, ale nové soubory budou do cache zapsány na základě aktuálního
422 běhu. Tato volba má pomoci hledat chybu v případě, kdy se cache systemtapu zdá
423 fungovat chybně. Pokud tato volba pomohla, provděpodobně je v někde v systemtapu
424 chyba, o které by vývojáři rádi věděli. Prosím, nahlašte ji.
425
426 .TP
427 \fB\-\-privilege\fR[=\fIstapusr\fR | =\fIstapsys\fR | =\fIstapdev\fR]
428 Tato volba zkontroluje skript na přítomnost konstruktů, které nejsou povoleny
429 pro zadanou úroveň oprávnění (viz \fINEPRIVILEGOVANÍ UŽIVATELÉ\fR). Pokud
430 skript nepovolené konstrukty obsahuje, kompilace skončí chybou.
431
432 Pokud je \fIstapusr\fR nebo \fIstapsys\fR specifikováno při použití
433 kompilačního serveru (viz \fI\-\-use\-server\fR), pak server zkontroluje skript
434 a, pokud kompilace uspěje, server kryptograficky podepíše výsledný modul, kde
435 specifikuje, že daný modul je bezpečný pro použití uživatelem s danou úrovní
436 oprávnění.
437
438 Pokud se \fI\-\-privilege\fR nespecifikuje, \fI\-pN\fR se také nespecifikuje s
439 N < 5 a daný uživatel není \fIroot\fR ani člen skupiny \fIstapdev\fR, pak
440 \fIstap\fR automaticky přidá odpovídající \fI\-\-privilege\fR volbu k již
441 specifikovaným volbám.
442
443 .TP
444 .BI \-\-unprivileged
445 Ekvivalent pro \fI\-\-privilege=stapusr\fR.
446
447 .TP
448 \fB\-\-use\-server\fR[=\fIHOSTNAME\fR[\fI:PORT\fR] | =\fIIP_ADDRESS\fR[\fI:PORT\fR] | =\fICERT_SERIAL\fR]
449 Specifikuje kompilační server(y) pro kompilaci, a/nebo - v kombinaci s
450 .I \-\-list\-servers
451 a
452 .I \-\-trust\-servers
453 (viz níže) pro výpis serverů. Pokud je tato volba použita bez parametrů v
454 neprivilegovaném režimu (viz
455 .IR \-\-privilege )
456 , pak výchozí server, který bude pro kompilaci použit, bude některý z
457 dostupných kompatibilních serverů "online SSL peer", a zároveň "module signer". Jinak bude
458 jako výchozí server použit některý z dostupných kompatibilních serverů "online SSL
459 peer".
460 .I \-\-use\-server
461 lze použít opakovaně a v tomto případě bude seznam použitelných serverů
462 postupně rozšiřován v daném pořadí.
463 Servery lze specifikovat pomocí hostaname, IP adresy, nebo seriálním číslem
464 certifikátu (získaným prostřednictvím
465 .IR \-\-list\-servers ).
466 Poslední možnost je nejběžnější pro (od)nastavování důvěryhodnosti serveru. Viz
467 .I \-\-trust\-servers
468 níže.
469
470 Pokud je server specifikován pomocí hostname nebo IP adresy, pak je volitelně
471 možné určit i číslo portu. To je vhodné pro přístup k serverům, které nejsou na
472 lokální síti, nebo pro specifikování konkrétního serveru.
473
474 IP adresou může být jak IPv4, tak IPv6.
475
476 Pokud existuje více než jedno rozhraní s danou link-local IPv6 adresou, pak je
477 možné zvolit konkrétní rozhraní připojením znaku "%" a názvu rozhraní k adrese,
478 například: "fe80::5eff:35ff:fe07:55ca%eth0".
479
480 Pro určení čísla portu IPv6 adresy je nutné uzavřít adresu do hranatých závorek
481 , aby došlo k oddělení adresy od čísla portu. Například:
482 "[fe80::5eff:35ff:fe07:55ca]:5000" nebo "[fe80::5eff:35ff:fe07:55ca%eth0]:5000".
483
484 Pokud \fI\-\-use\-server\fR nebylo specifikováno,
485 \fI\-pN\fR nebylo specifikováno s N < 5,
486 a uživatel není \fIroot\fR,
487 není člen skupiny \fIstapdev\fR, ale je členem skupiny
488 \fIstapusr\fR, pak \fIstap\fR automaticky
489 přidá \fI\-\-use\-server\fR k již specifikovaným volbám.
490
491 .TP
492 \fB\-\-use\-server\-on\-error\fR[=\fByes\fR|=\fBno\fR]
493 Požádá stap, aby zkusil kompilaci znovu s použitím kompilačního serveru,
494 pokud lokální kompilace selže. Pokud tato volba není specifikována, pak se za
495 výchozí považuje \fB\-\-use\-server\-on\-error\fR=\fBno\fR
496
497 \fB\-\-use\-server\-on\-error\fR je ekvivalentem pro
498 \fB\-\-use\-server\-on\-error\fR=\fByes\fR.
499
500 Kompilace může být přerušena pro určitý typ chyby, jako například nedostatek
501 dat nebo zdrojů. K tomu může dojít i během rekompilace. Pro rekompilaci budou
502 servery voleny automaticky tak, jako by byla použita volba
503 \fI\-\-use\-server\fR bez parametrů.
504
505 .TP
506 .BI \-\-list\-servers "[=SERVERS]"
507 Zobrazí stav požadovaných
508 .IR SERVERS ,
509 kde
510 .I SERVERS
511 je čárkou oddělený seznam atributů popisujících servery. Sjednocení atributů
512 slouží k vygenerování seznamu serverů. Dostupné atributy jsou:
513 .RS
514 .TP
515 .BI all
516 specifikuje všechny známé servery (důvěryhodné servery "SSL peer", důvěryhodné servery "module
517 signer", servery ve stavu "online").
518 .TP
519 .BI specified
520 určuje servery specifikované pomocí
521 .IR \-\-use\-server .
522 .TP
523 .BI online
524 vybere ze seznamu jen ty servery, které jsou aktuálně ve stavu "online".
525 .TP
526 .BI trusted
527 vybere ze seznamu jen důvěryhodné servery "SSL peer".
528 .TP
529 .BI signer
530 vybere ze seznamu jen servery "module signer", viz
531 .IR \-\-privilege .
532 .TP
533 .BI compatible
534 vybere jen kompatibilní servery ve smyslu kernel release a architektury.
535 .RE
536 .IP
537 Pokud není dán žádný argument, pak výchozí volbou je
538 .BR specified .
539 Pokud žádné servery nebyly specifikovány pomocí
540 .IR \-\-use\-server ,
541 pak budou vypsány výchozí servery pro
542 .IR \-\-use\-server .
543
544 Poznamenejme, že
545 .IR \-\-list\-servers
546 používá
547 .IR avahi\-daemon
548 k detekci online serverů. Pokud tato služba není dostupná, pak
549 .IR \-\-list\-servers
550 nebude detekovat žádné
551 .IR online
552 servery. Aby
553 .IR \-\-list\-servers
554 detekoval servery poslouchající na IPv6 adresách, musí konfigurační soubor avahi
555 démona,
556 .IR /etc/avahi/avahi-daemon.conf
557 , obsahovat "use-ipv6=yes". Po případné úpravě konfiguračního souboru je
558 třeba službu restartovat.
559
560 .TP
561 .BI \-\-trust\-servers "[=TRUST_SPEC]"
562 Nastavit nebo odvolat natavení důvěryhodnosti kompilačního serveru
563 specifikovaného pomocí
564 .IR \-\-use\-server
565 podle TRUST_SPEC, kde TRUST_SPEC je čárkou oddělený seznam typů důvěryhodnosti.
566 Podporované typy jsou:
567 .RS
568 .TP
569 .BI ssl
570 důvěřovat specifikovaným serverům jako "SSL peer".
571 .TP
572 .BI signer
573 důvěřovat specifikovaným serverům jako "module signer" (viz
574 .IR \-\-privilege ).
575 Jen root může nastavit
576 .BR signer.
577 .TP
578 .BI all\-users
579 důvěřovat specifikovaným serverům jako "SSL peer" pro všechny uživatele na
580 localhostu. Výchozí chování je nastavit tento typ důvěřování jen pro aktuálního
581 uživatele. Důvěra typu "module signer" se vždy vztahuje na všechny uživatele.
582 Jen root může nastavit
583 .BR all\-users .
584 .TP
585 .BI revoke
586 ruší určenou relaci důvěry. Výchozí chování je zapnutí relace důvěry.
587 .TP
588 .BI no\-prompt
589 nežádat uživatele o potvrzení před provedením akce. Výchozí chování je požádat
590 o potvrzení před provedením akce.
591 .RE
592 .IP
593 Pokud žádný argument není nastaven, použije se výchozí hodnota
594 .BR ssl .
595 Pokud pomocí
596 .IR \-\-use\-server ,
597 nebyly určené žádné servery, žádná relace důvěry nebude nastavena ani zrušena.
598 .IP
599 Dokud se nespecifikuje \fBno\-prompt\fR, uživatel bude požádán o potvrzení
600 požadované akce.
601
602 .TP
603 .BI \-\-dump-probe-types
604 Vypíše všechny podporované typy sond a skončí. Pokud je též nastaveno
605 .IR \-\-privilege=stapusr
606 , pak tento seznam bude omezen tak, aby vidět byly pouze sondy, které má
607 daný uživatel právo použít.
608
609 .TP
610 .BI \-\-dump-probe-aliases
611 Vypíše všechny přezdívky nalezené v tapset skriptech a skončí.
612
613 .TP
614 .BI \-\-dump-functions
615 Vypíše všechny veřejné funkce nalezené v tapset skriptech a skončí. Také
616 vypíše jejich parametry a typy. Návratový typ "unknown" značí, že daná funkce
617 nevrací hodnotu. Poznamenejme, že ne všechny návratové typy / typy parametrů je
618 vždy možné při syntaktické analýze stanovit. Nestanovené typy budou též
619 označeny jako "unknown". Funkce \-\-dump-functions je náročná na paměť a proto
620 nemusí správně fungovat s \fI\-\-use-server\fR pokud na cílovém systému narazí
621 na rlimit pro paměť procesu, například prostřednictvím konfiguračního souboru
622 \fI~stap-server/.systemtap/rc\fR, viz \fIstap-server\fR(8).
623
624
625 .TP
626 .BI \-\-remote " URL"
627 Provede skript na vzdáleném stroji. Tuto volbu je možné opakovat pro provedení
628 skriptu na více strojích. Procesní fáze 1-4 se provedou lokálně, jak je běžné,
629 a pak během fáze 5, se modul zkopíruje na specifikované stroje a na nich
630 provede. Přijatelné URL jsou:
631
632 .RS
633 .TP
634 \fB[USER@]HOSTNAME\fR, \fBssh://[USER@]HOSTNAME\fR
635 Tento režim využívá SSH, volitelně s využitím specifického uživatelského jména
636 username. Pokud je použit uživatelský ssh_config, je třeba do něj přidat
637 \fBSendEnv LANG\fR pro zachování nastavení lokalizace.
638
639 .TP
640 \fBlibvirt://DOMAIN\fR, \fBlibvirt://DOMAIN/LIBVIRT_URI\fR
641 Tento režim využívá ke spuštění skriptu \fIstapvirt\fR v doméně obsluhované
642 libvirt démonem. Volitelně je možno specifikovat LIBVIRT_URI pro připojení ke
643 specifickému driveru nebo vzdálenému stroji. Například pro připojení k místnímu
644 privilegovanému QEMU driveru použijte:
645
646 .SAMPLE
647 \-\-remote libvirt://MyDomain/qemu:///system
648 .ESAMPLE
649 Viz
650 .nh
651 <http://libvirt.org/uri.html>
652 .hy
653 pro podrobnosti ohledně podporovaných formátů URI. Viz též
654 \fIstapvirt\fR(1).
655
656 .TP
657 \fBunix:PATH\fR
658 V tomto režimu dojde k připojení přes UNIX soket. Toho lze využít pro připojení
659 přes QEMU virtio-serial port pro spuštění skriptu uvnitř běžícího virtuálního
660 stroje.
661
662 .TP
663 \fBdirect://\fR
664 Loopback režim pro spouštění na localhostu.
665 .RE
666 .IP
667
668 .TP
669 .BI \-\-remote\-prefix
670 Oprefixuje každou řádku výstupu "N: ", kde N je index vzdáleného stroje ze
671 kterého daný výstup pochází.
672
673 .TP
674 .BI \-\-download\-ladicíinfo "[=OPTION]"
675 Podle OPTION zapne, vypne, nebo nastaví timeout pro funkci automatického
676 stahování balíčků s ladicími informacemi, kterou nabízí ABRT. Přípustné
677 hodnoty pro OPTION jsou:
678 .RS
679 .TP
680 .BI yes
681 povolí automatické stahování bez časového omezení. Totéž jako
682 .IR \-\-download\-debuginfo
683 bez parametru.
684 .TP
685 .BI no
686 explicitně vypne automatické stahování Totéž jako nepoužití
687 \-\-download\-debuginfo vůbec.
688 .TP
689 .BI ask
690 ukáže výstup ABRTu a dotáže se uživatele, zda se má pokračovat v downloadu.
691 Žádný timeout nebude nastaven.
692 .TP
693 .BI <timeout>
694 specifikuje timeout jako pozitivní celé číslo vyjadřující maximální počet
695 sekund pro download.
696 .RE
697 .IP
698
699 .TP
700 .BI \-\-rlimit-as "=NUM"
701 Určí maximální velikost virtuální paměti procesu v bajtech. Bez
702 specifikace NUM nebude žádný limit nastaven.
703
704 .TP
705 .BI \-\-rlimit-cpu "=NUM"
706 Určí limit pro čas CPU v sekundách. Bez specifikace NUM není žádný limit
707 nastaven.
708
709 .TP
710 .BI \-\-rlimit-nproc "=NUM"
711 Určí maximální počet procesů které může systemtap vytvořit. Bez
712 specifikace NUM není žádný limit nastaven.
713
714 .TP
715 .BI \-\-rlimit-stack "=NUM"
716 Nastaví maximální velikost zásobníku v bajtech. Bez specifikace NUM není žádný
717 limit nastaven.
718
719 .TP
720 .BI \-\-rlimit-fsize "=NUM"
721 Nastaví maximální velikost souboru, který je možno vytvořit, v bajtech. Bez
722 specifikace NUM není žádný limit nastaven.
723
724 .TP
725 .BI \-\-sysroot "=DIR"
726 Nastaví "sysroot" adresář, kde budou umístěny cílové soubory (programy, knihovny
727 atd.) Po nastavení \fI\-r RELEASE\fR bude v adresáři "sysroot" hledán "build"
728 adresář jádra, ovšem po nastavení \fI\-r /DIR\fR nebude "sysroot" prohledáván na
729 "build" adresář jádra.
730
731 .TP
732 .BI \-\-sysenv "=VAR=VALUE"
733 Nastaví alternativní hodnotu proměnné prostředí pokud se tato hodnota na
734 vzdáleném systému liší. Předpokládá se, že proměnné vyjadřující cesty budou
735 uvedeny jako relativní cesty vzhledem k \fI\-\-sysroot\fR (pokud je nastaven).
736
737 .TP
738 .BI \-\-suppress\-time\-limits
739 Potlačí \-DSTP_OVERLOAD*, \-DMAXACTION a \-DMAXTRYLOCK. Vyžaduje guru režim (-g).
740
741 .TP
742 .BI \-\-runtime "=MODE"
743 Nastaví runtime režim pro procesní fázi 5. Validní hodnoty jsou \fIkernel\fR
744 (výchozí), \fIdyninst\fR a \fIbpf\fR. Viz sekce
745 .BR ALTERNATIVNÍ\ RUNTIME .
746
747 .TP
748 .BI \-\-dyninst
749 Zkratka pro \fI\-\-runtime=dyninst\fR.
750
751 .TP
752 .BI \-\-save-uprobes
753 Na strojích, kde si SystemTap musí sestavit svůj vlastní modul "uprobes" (jádra
754 před 3.5), tato volba instruuje SystemTap, aby po sestavení tento pomocný modul
755 zachoval v aktuálním adresáři.
756
757 .TP
758 .BI \-\-target-namespaces "=PID"
759 Nastavuje cílový "namespace" (jmenný prostor procesů) na "namespace" do kterého
760 patří PID. Volba souvisí s "namespace\-aware" tapset funkcemi. Pokud cílový "namespace"
761 není specifikován, použije se "namespace" v kterém běží stap.
762
763 .TP
764 .BI \-\-monitor "=INTERVAL"
765 Umožňuje zobrazovat informace o stavu modulu (čas běhu, jméno modulu, id
766 uživatele, který modul aktivoval, informace o paměti, globální proměnné,
767 seznam sond včetně jejich statistik). Je možno nastavit volitelný parametr
768 INTERVAL, který určuje obnovovací frekvenci stavového okna v sekundách. Činnost
769 modulu lze ovládat následujícími klávesami:
770
771 .RS
772 .TP
773 .BI r
774 přenastaví všechny globální proměnné na jejich výchozí hodnoty nebo na nulu,
775 pokud výchozí hodnota nebyla určena.
776 .TP
777 .BI s
778 cyklicky mění hodnoty daného atributu za účelem změny třídění seznamu sond.
779 .TP
780 .BI t
781 umožňuje aktivovat/deaktivovat sondu indexem.
782 .TP
783 .BI navigační-klávesy
784 Klávesami j/k/Up/Down lze posouvat seznam sond. Klávesami d/u/PgDn/PgUp
785 lze rolovat v statistice modulu.
786 .RE
787
788 .SH ARGUMENTY
789
790 Všechny další argumenty z příkazové řádky se předají kompilátoru ke
791 zpracování. Viz níže.
792
793 .SH SKRIPTOVACÍ JAZYK
794
795 Skriptovací jazyk systemtapu připomíná
796 .IR awk " a " C .
797 Existují v něm dva hlavní konstrukty: sondy a funkce. V jejich rámci se používají
798 příkazy a výrazy se syntaxí podobnou syntaxi jazyka C.
799
800 .SS OBECNÁ SYNTAXE
801 Bílé místo se ignoruje. Podporovány jsou komentáře tří typů:
802 .RS
803 .br
804 .BR # " ... shell styl, do konce řádku, mimo $# a @#"
805 .br
806 .BR // " ... C++ styl, do konce řádku"
807 .br
808 .BR /* " ... C styl ... " */
809 .RE
810 Literály jsou buďto řetězce uzavřené v uvozovkách (dovolují obvyklé C escape
811 sekvence se zpětnými lomítky, které lze řetězit podobně jako v C), nebo celá
812 čísla (dekadická, hexadecimální, nebo oktalová, zapsaná stejně jako v C).
813 Maximální délka řetězce je rozumně omezená na několik set bajtů. Celá čísla
814 jsou 64-bitová se znaménkem. Parser formálně přijímá i kladná čísla nad 2**63,
815 pro které pak používá modulo aritmetiku z důvodu přetečení (wrap around).
816
817 .PP
818 Na konci příkazové řádky lze skriptům předat parametry. V rámci
819 skriptu k nim pak lze přistupovat prostřednictvím
820 .B $1 ... $<NN>
821 pokud jde literály neuzavřené do uvozovek, nebo
822 .B @1 ... @<NN>
823 pokud jde o řetězcové literály uzavřené do uvozovek. Počet argumentů je
824 přístupný prostřednictvím
825 .B $#
826 (jakožto číslo neuzavřené do uvozovek) nebo prostřednictvím
827 .B @#
828 (jakožto číslo do uvozovek uzavřené). Tyto symboly lze použit na místě
829 libovolné lexikální jednotky skriptu, a k jejich vyhodnocení dojde již v
830 počáteční fázi překladu (preprocessing).
831
832 .SS FÁZE PŘEDZPRACOVÁNÍ (PREPROCESSING)
833 Součástí lexikální analýzy je jednoduchá fáze předzpracování. V ní lze
834 (ne)vyhodnocovat části kódu na základě podmínky. Příslušná syntaxe se obecně
835 podobá ternárnímu operátoru:
836 .RB podmínka " ? " výraz1 " : " výraz2
837 .SAMPLE
838 .BR %( " PODMÍNKA " %? " VÝRAZ-1 " %)
839 .BR %( " PODMÍNKA " %? " VÝRAZ-1 " %: " VÝRAZ-2 " %)
840 .ESAMPLE
841 PODMÍNKA je buďto výraz, jehož formát je určen prvním klíčovým slovem, nebo
842 porovnání řetězcových či numerických literálů, nebo výraz složený z takových
843 podmínek s využitím operátorů || a &&. Nicméně, závorky zde zatím nejsou
844 podporovány, takže je důležité mít na zřeteli, že && má při vyhodnocení
845 přednost před ||.
846
847 .PP
848 Pokud první částí podmínky je identifikátor
849 .BR kernel_vr " nebo " kernel_v
850 odkazující se k verzi jádra s příponou ("2.6.13\-1.322FC3smp"), nebo bez
851 přípony ("2.6.13"), pak následovat musí jeden z operátorů porovnání:
852 .BR < ", " <= ", " == ", " != ", " > ", a " >= ,
853 a třetí částí podmínky je řetězcový literál vyjadřující verzi jádra v RPM-stylu.
854
855 Podmínka se považuje za splněnou, pokud verze běžícího jádra (volitelně
856 předefinovaná volbou
857 .BR \-r
858 ) se srovnává se zadanou hodnotou. Srovnání provádí glibc funkce
859 .BR strverscmp() .
860
861 Pokud operátorem je jednoduchá rovnost
862 .RB ( == ),
863 nebo nerovnost
864 .RB ( != ),
865 a pravý operand obsahuje zástupné symboly
866 .RB ( * " nebo " ? " nebo " [ "),"
867 , pak celý výraz bude interpretován jako "wildcard (mis)match" a bude
868 vyhodnocen glibc funkcí
869 .BR fnmatch() .
870
871
872 .PP
873 Pokud první částí podmínky je
874 .BR arch
875 odkazující se k architektuře procesoru (pojmenované podle ARCH/SUBARCH v
876 terminologii jádra), pak druhou částí podmínky je jeden z operátorů:
877 .BR == " nebo " != ,
878 a třetí částí podmínky je požadovaný řetězcový literál, který může obsahovat
879 zástupné symboly ("wildcard (mis)match").
880 .PP
881
882 Podobně, pokud první složkou podmínky je identifikátor jako
883 .BR CONFIG_*
884 odkazující se ke konfigurační volbě jádra, pak druhou částí podmínky je
885 .BR == " nebo " != ,
886 a třetí částí podmínky je řetězcový literál odpovídající volby (obvykle "y",
887 nebo "m"). Neexistující, nebo nenastavené konfigurační volby v tomto kontextu
888 odpovídají prázdnému řetězci. Vyhodnocení opět probíhá jako "wildcard
889 (mis)match" s využitím
890 .BR fnmatch() .
891
892 .PP
893 Pokud první částí je identifikátor
894 .BR systemtap_v ,
895 pak se test odkazuje k verzi systemtapu, kterou lze volitelně pro staré skripty
896 nastavit prostřednictvím volby
897 .BI \-\-compatible .
898 Operátor porovnání je jako u
899 .BR kernel_v
900 , a pravým operandem je řetězec vyjadřující verzi jádra. Viz též sekce
901 ZASTARÁVÁNÍ níže.
902 .PP
903
904 Pokud první částí podmínky je
905 .BR systemtap_privilege ,
906 pak se test odkazuje k úrovni oprávnění se kterou je systemtap skript překládán.
907 V tomto případě je podmínkou jeden z operátorů
908 .BR == " nebo " != ,
909 a třetí částí podmínky je jeden z řetězcových literálů "stapusr", "stapsys",
910 nebo "stapdev".
911
912 .PP
913 Pokud první částí podmínky je identifikátor
914 .BR guru_mode ,
915 pak test ověřuje, zda je systemtap skript překládán v "guru" režimu (-g).
916 Operátorem pro tento případ může být
917 .BR == " nebo " != ,
918 a třetí částí podmínky je číslo. Buďto 1, nebo 0.
919 .PP
920
921 Pokud prvním indetifikátorem je
922 .BR runtime ,
923 testuje se runtime režim (--runtime). Viz sekce
924 .BR ALTERNATIVNÍ\ RUNTIME
925 níže pro informaci o dostupných runtime backendech.
926 Porovnávací operátor v tomto případě je
927 .BR == " nebo " != ,
928 a třetí částí podmínky je řetězcový literál odpovídající runtime. Porovnání je
929 typu "wildcard (mis)match" s využitím
930 .BR fnmatch()
931
932 .PP
933 Poslední možností je situace, kdy PODMÍNKA srovnává prosté číselné, nebo
934 řetězcové literály.
935
936 .PP
937 VÝRAZ-1 a VÝRAZ-2 představují výskyt nuly nebo více obecných lexikálních
938 jednotek (které mohou obsahovat další vložené podmínky preprocesoru), a
939 jsou preprocesorem předány na vstup parseru v závislosti na vyhodnocení uvedené
940 podmínky. Například následující kód vyvolá kompilační chybu v případě že verze
941 běžícího jádra na cílovém systému je novější, než 2.6.5:
942 .SAMPLE
943 %( kernel_v <= "2.6.5" %? **ERROR** %) # "invalid token sequence"
944 .ESAMPLE
945
946 Naproti tomu následující kód umožní elegantně se vyrovnat s různými verzemi jádra:
947 .SAMPLE
948 probe kernel.function (
949 %( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
950 %( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
951 UNSUPPORTED %) %)
952 ) { /* ... */ }
953
954 %( arch == "ia64" %?
955 probe syscall.vliw = kernel.function("vliw_widget") {}
956 %)
957 .ESAMPLE
958
959 .SS MAKRA PREPROCESORU
960 Preprocesor přijímá jednoduchá makra a vyhodnocuje je v rámci samostatné
961 procesní fáze před vyhodnocením podmínek.
962
963 .PP
964 Makra se definují následující konstrukcí:
965 .SAMPLE
966 @define NAME %( BODY %)
967 @define NAME(PARAM_1, PARAM_2, ...) %( BODY %)
968 .ESAMPLE
969
970 Makra (a také parametry uvnitř těla maker) jsou přístupná přidáním prefixu "@"
971 před jejich jméno"
972 .SAMPLE
973 @define foo %( x %)
974 @define add(a,b) %( ((@a)+(@b)) %)
975
976 @foo = @add(2,2)
977 .ESAMPLE
978 .PP
979
980 K expanzi maker v současnosti dochází v samostatné preprocesní fázi před
981 zpracováním podmínek. Proto dojde k vyhodnocení všech maker v rámci
982 kondicionálu bez ohledu na konkrétní podmínku. To může vést k nezamýšleným
983 chybám:
984
985 .SAMPLE
986 // Následující kód způsobí chybu:
987 %( CONFIG_UPROBE == "y" %?
988 @define foo %( process.syscall %)
989 %:
990 @define foo %( **ERROR** %)
991 %)
992
993 // Následující kód bude fungovat správně:
994 @define foo %(
995 %( CONFIG_UPROBE == "y" %? process.syscall %: **ERROR** %)
996 %)
997 .ESAMPLE
998
999 První příklad je chybný, protože vyvolá duplicitní definici makra "foo".
1000
1001 Za normálních okolností je definice platná lokálně - pouze v souboru kde se
1002 vyskytuje. Makro definované v tapset skriptu tedy není veřejně použitelné v
1003 rámci uživatelského skriptu. Makra, která mají být veřejně dostupná, lze
1004 sdružovat do knihoven s příponou ".stpm" nacházející se v "tapset search path".
1005 Tyto soubory mohou obsahovat @define konstrukty, které budou dostupné nejen ve
1006 všech tapsetech, ale i v uživatelských skriptech. Volitelně mohou být definice
1007 maker v rámci ".stpm" souborů zabaleny v kondicionálech preprocesoru.
1008
1009 .SS KONSTANTY
1010 V rámci tapset skriptů, nebo guru skriptů je možno přistupovat ke konstantním
1011 symbolům, jako jsou například makra jazyka C, prostřednictvím vestavěného
1012 operátoru @const(). Pokud je potřeba přidat příslušný #include dodatečného
1013 hlavičkového souboru, lze tak učinit prostřednictvím vloženého kódu jazyka C.
1014 .SAMPLE
1015 @const("STP_SKIP_BADVARS")
1016 .ESAMPLE
1017
1018 .SS PROMĚNNÉ
1019 Identifikátory pro proměnné a funkce jsou alfanumerické sekvence, které mohou
1020 obsahovat \fB_\fR a \fB$\fR. Nesmí začínat číslicí (stejně jako v C). Proměnné
1021 jsou lokální vzhledem ke svému bloku (funkce nebo sondy) a jejich životnost je
1022 spojena s tímto blokem.
1023
1024 .PP
1025 Skalární proměnné jsou implicitně řetězcového, nebo celočíselného typu.
1026 Asociativní pole mohou také obsahovat řetězcové nebo celočíselné hodnoty a jako
1027 klíč jim slouží n-tice řetězců nebo celých čísel. Zde je několik příkladů:
1028
1029 .SAMPLE
1030 var1 = 5
1031 var2 = "bar"
1032 array1 [pid()] = "name" # jednoduchý číselný klíč pole
1033 array2 ["foo",4,i++] += 5 # n-tice jako klíč pole
1034 if (["hello",5,4] in array2) println ("yes") # test na členství
1035 .ESAMPLE
1036 .PP
1037
1038 Překladač provádí
1039 .I typové odvození (type inference)
1040 na všech identifikátorech včetně indexů polí a parametrů funkcí.
1041 Nekonzistentní zacházení s typy způsobí chybu překladu.
1042
1043 .PP
1044 Proměnné lze definovat jako globální, takže mohou být sdíleny mezi sondami a
1045 funkcemi, a žijí stejně dlouho jako celé systemtap sezení. Pro globální
1046 proměnné existuje jediný jmenný prostor. Přístup ke globálním proměnným je
1047 chráněn zámky, viz
1048 .B BEZPEČNOST A OCHRANA SOUKROMÍ.
1049 Globální proměnnou lze deklarovat kdekoli ve vnější úrovni zdrojového kódu,
1050 tedy mimo bloky sond a funkcí. Globální proměnné, kterým byla přiřazena
1051 hodnota, ale nikdy nebyla čtena, budou automaticky zobrazeny na konci systemtap
1052 sezení. Překladač se pokusí odvodit datový typ z hodnot a případně, pokud jde
1053 o pole, i z klíčů. Volitelně lze globální proměnnou inicializovat řetězcovým,
1054 nebo číselným literálem. Zde jsou příklady deklarace globálních proměnných:
1055
1056 .SAMPLE
1057 .BR global " var1" , " var2" , " var3=4"
1058 .ESAMPLE
1059 .PP
1060
1061 Globální proměnné lze také použít jako parametry systemtap modulu. Toho lze
1062 dosáhnout buďto použitím přepínače stap \-G, nebo modul připravit předem pomocí
1063 stap \-p4 a parametry mu předat později při jeho zavádění na příkazové řádce
1064 programu staprun. Viz
1065 .IR staprun (8) .
1066
1067 .PP
1068 Rozsah platnosti globální proměnné lze omezit na tapset soubor, nebo na
1069 uživatelský skript prostřednictvím klíčového slova "private". V tom případě je
1070 klíčové slovo "global" volitelné. Následující deklarace označuje var1 a var2 jako
1071 privátní globální proměnné:
1072
1073 .SAMPLE
1074 .BR private " global" " var1=2"
1075 .BR private " var2"
1076 .ESAMPLE
1077 .PP
1078
1079 Pole mají omezenou velikost parametrem MAXMAPENTRIES. Viz
1080 .B BEZPEČNOST A OCHRANA SOUKROMÍ
1081
1082 Volitelně lze polím (která jsou vždy globální) nastavit maximální velikost v
1083 hranatých závorkách, čímž se předefinuje MAXMAPENTRIES pro dané pole.
1084 Poznamenejme, že velikost se vztahuje jen k počtu prvků, nikoliv k celkové
1085 velikosti pole v paměti. Příklad:
1086 .SAMPLE
1087 .BR global " tiny_array[10]" , " normal_array" , " big_array[50000]"
1088 .ESAMPLE
1089 .PP
1090
1091 Polím lze nastavit příznak "%". To způsobí, že pokud do pole přidáme více
1092 prvků, než pro kolik je dimenzováno, začnou staré prvky mizet (LIFO). To platí
1093 jak pro asociativní, tak pro statistická pole, viz níže. Příklad:
1094
1095 .SAMPLE
1096 .BR global " wrapped_array1%[10]", " wrapped_array2%"
1097 .ESAMPLE
1098
1099 .PP
1100 Mnohé sondy poskytují kontextové proměnné, což jsou hodnoty získané za běhu z
1101 jádra, nebo zkoumané uživatelské aplikace. Jejich identifikátory začínají
1102 znakem \fB$\fR. Sekce KONTEXTOVÉ PROMĚNNÉ v manuálové stránce
1103 .IR stapprobes (3stap)
1104 obsahuje jejich seznamy pro jednotlivé typy sond. Tyto kontextové proměnné se
1105 stanou normálními řetězcovými nebo numerickými proměnnými použitelnými ve
1106 skriptu, jakmile provedeme příslušné přiřazení (např. foo=$foo). Podívejte se
1107 níže na sekci PŘETYPOVÁNÍ, kde je popsáno jak takovou proměnnou přetypovat zpět
1108 na ukazatel je-li to třeba.
1109
1110 .SS PŘÍKAZY
1111 Příkazy umožňují procedurální řízení běhu skriptu. Mohou se vyskytovat uvnitř
1112 funkcí a obslužných rutin sond. Celkový počet příkazů, které je v reakci na
1113 nějakou událost možno spustit, je omezen na hodnotu definovanou makry
1114 MAXACTION_* ve vygenerovaném C-kódu a pohybuje se kolem 1000.
1115
1116 .TP
1117 EXP
1118 Vyhodnotit řetězcový, nebo číselný výraz a zahodit hodnotu.
1119
1120 .TP
1121 .BR { " STMT1 STMT2 ... " }
1122 Vykonat každý příkaz v sekvenci v tomto bloku. Poznamenejme, že oddělovače a
1123 znaky pro ukončení příkazu nejsou mezi jednotlivými příkazy nezbytné.
1124
1125 .TP
1126 .BR ;
1127 Prázdný příkaz, nedělat nic. Je užitečný jako volitelný oddělovač mezi příkazy
1128 ke zlepšení detekce syntaktických chyb a k upřesnění některých syntaktických
1129 nejednoznačností gramatiky.
1130
1131 .TP
1132 .BR if " (EXP) STMT1 [ " else " STMT2 ]"
1133 Porovnat číselný výraz EXP s nulou. Pak vykonat příkaz STMT1 (EXP není nula),
1134 nebo příkaz STMT2 (EXP je nula).
1135
1136 .TP
1137 .BR while " (EXP) STMT"
1138 Dokud má číselný výraz EXP nenulovou hodnotu, spouštěj STMT.
1139
1140 .TP
1141 .BR for " (EXP1; EXP2; EXP3) STMT"
1142 Vykoná EXP1 jako inicializaci. Dokud EXP2 má nenulovou hodnotu, bude vykonávat
1143 STMT a iterační výraz EXP3.
1144
1145 .TP
1146 .BR foreach " (VAR " in " ARRAY [ "limit " EXP ]) STMT"
1147 Cyklení přes každý prvek globálního pole ARRAY s přiřazením aktuálního prvku
1148 proměnné VAR. Pole není v rámci STMT dovoleno měnit. Přidáním operátoru
1149 .BR + " nebo " \-
1150 za identifikátor VAR nebo ARRAY, se zajistí iterování přes
1151 setříděné pole jedním, nebo druhým směrem. Pokud pole obsahuje statistické
1152 agregátory, pak přidáním požadovaného operátoru
1153 .BR @operator
1154 mezi ARRAY a symbol
1155 .BR + " nebo " \-
1156 určíme třídicí agregační funkci. Viz příklad níže v sekci STATISTIKA. Výchozí je
1157 .BR @count .
1158 S využitím volitelného klíčového slova
1159 .BR limit
1160 lze maximální počet iterací omezit na EXP. Poznamenejme, že EXP se vyhodnocuje
1161 na začátku smyčky.
1162
1163 .TP
1164 .BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [ "limit " EXP ]) STMT"
1165 Podobně jako výše, ovšem v tomto případě je klíčem pole n-tice hodnot. Třídicí
1166 příponu lze použít maximálně na jednom z prvků n-tice.
1167
1168 .TP
1169 .BR foreach " ([VAR1, VAR2, ...] " in " ARRAY [INDEX1, INDEX2, ...] [ "limit " EXP ]) STMT"
1170 Podobně jako výše, ovšem iterovat se bude pouze přes prvky, kde klíč vyhovuje
1171 dané hodnotě. Pro určení indexu lze použít znak *, se kterým bude zacházeno jako
1172 se zástupným symbolem.
1173
1174 .TP
1175 .BR foreach " (VAR0 = VAR " in " ARRAY [ "limit " EXP ]) STMT"
1176 Tato varianta foreach uchová aktuální hodnotu při každé iteraci ve VAR0, takže
1177 bude odpovídat ARRAY[VAR]. Tohle analogicky funguje s n-ticí klíčů. Třídicí
1178 přípony na VAR0 mají stejný význam jako na ARRAY.
1179
1180 .TP
1181 .BR foreach " (VAR0 = VAR " in " ARRAY [INDEX1, INDEX2, ...] [ "limit " EXP ]) STMT"
1182 Podobné jako výše, ovšem iteruje se pouze přes prvky, kde klíče vyhovují daným
1183 hodnotám. Pro určení indexu lze použít znak * se kterým bude zacházeno jako se
1184 zástupným symbolem.
1185
1186 .TP
1187 .BR break ", " continue
1188 Ukončit, nebo znovu iterovat vnitřní smyčku. Aplikovatelné na
1189 .RB while " nebo " for " nebo " foreach.
1190
1191 .TP
1192 .BR return " EXP"
1193 Vrátit hodnotu EXP z funkce. Příkaz return není ve funkci povinný. Pokud se
1194 vynechá, bude funkce mít speciální návratový datový typ "unknown".
1195
1196 .TP
1197 .BR next
1198 Ihned ukončí obslužnou rutinu sondy. To je obzvlášť užitečné u přezdívek,
1199 které používají filtrovací podmínky.
1200
1201 .TP
1202 .BR try " { STMT1 } " catch " { STMT2 }"
1203 Vykonej příkazy v prvním bloku STMT1. Pokud při tom dojde k chybě běhu,
1204 ukonči STMT1 a začni provádět STMT2. Případné chyby v STMT2 se budou propagovat
1205 do vnějšího catch bloku, pokud tam takový je.
1206
1207 .TP
1208 .BR try " { STMT1 } " catch "(VAR) { STMT2 }"
1209 Podobně jako v předchozím případě, ale navíc se chybová hláška, jakožto řetězec,
1210 uchová v proměnné VAR.
1211
1212 .TP
1213 .BR delete " ARRAY[INDEX1, INDEX2, ...]"
1214 Odstraní z pole prvky určené n-ticí klíčů. Pokud n-tice klíčů obsahuje
1215 symbol * na místě indexu, bude s * zacházeno jako jako se zástupným symbolem.
1216
1217 Není chybou pokusit se smazat prvek, který neexistuje.
1218
1219 .TP
1220 .BR delete " ARRAY"
1221 Smazat všechny prvky pole ARRAY.
1222
1223 .TP
1224 .BR delete " SCALAR"
1225 Maže hodnotu SCALAR. Celočíselné proměnné budou vynulovány, řetězcové proměnné
1226 nastaveny na "", a statistické proměnné budou nastaveny do výchozího prázdného
1227 stavu.
1228
1229 .SS VÝRAZY
1230 SystemTap podporuje množství operátorů, které mají syntaxi a sémantiku velmi
1231 podobnou jejich C a awk protějškům. Aritmetické operace se provádějí v souladu
1232 s pravidly jazyka C pro celá čísla se znaménkem. Dělení nulou nebo přetečení
1233 rozsahu se detekuje a způsobí chybu.
1234
1235 .TP
1236 binární numerické operátory
1237 .B * / % + \- >> << & ^ | && ||
1238 .TP
1239 binární operátory nad řetězci
1240 .B .
1241 (spojení řetězců)
1242 .TP
1243 číselné přiřazovací operátory
1244 .B = *= /= %= += \-= >>= <<= &= ^= |=
1245 .TP
1246 řetězcové přiřazovací operátory
1247 .B = .=
1248 .TP
1249 unární číselné operátory
1250 .B + \- ! ~ ++ \-\-
1251 .TP
1252 operátory pro srovnávání čísel, řetězců a práci s regulárními výrazy
1253 .B < > <= >= == != =~ !~
1254 .TP
1255 ternární operátor
1256 .RB podmínka " ? " exp1 " : " exp2
1257 .TP
1258 seskupovací operátor
1259 .BR ( " exp " )
1260 .TP
1261 volání funkce
1262 .RB "fn " ( "[ arg1, arg2, ... ]" )
1263 .TP
1264 operátor testující členství v poli
1265 .RB exp " in " array
1266 .br
1267 .BR "[" exp1 ", " exp2 ", " ... "] in " array
1268 .br
1269 .BR "[" "*" ", " "*" ", ... "] in " array
1270
1271 .SS REGULÁRNÍ VÝRAZY
1272 Skriptovací jazyk systemtapu podporuje práci s regulárními výrazy.
1273 Základní operace testující (ne)shodu řetězce s regulárním výrazem:
1274 .SAMPLE
1275 .BR exp " =~ " regex
1276 .BR exp " !~ " regex
1277 .ESAMPLE
1278 První operand musí být výraz vyhodnotitelný na řetězec; druhý operand musí být
1279 řetězcový literál obsahující platný regulární výraz.
1280
1281 .PP
1282 Syntaxe regulárních výrazů podporuje většinu rozšířených regulárních výrazů POSIX
1283 standardu. Výjimkou je znovupoužití částí regulárního výrazu ("\\1").
1284
1285 .PP
1286 Po úspěšném nalezení je text vyhovující regulárnímu výrazu dostupný prostřednictvím
1287 tapsetových funkcí matched() a ngroups() následovně:
1288 .SAMPLE
1289 if ("an example string" =~ "str(ing)") {
1290 matched(0) // -> vrací "string", t.j. celý odpovídající řetězec
1291 matched(1) // -> vrací "ing", t.j. první odpovídající podřetězec
1292 ngroups() // -> vrací 2, t.j. počet odpovídajících skupin řetězců
1293 }
1294 .ESAMPLE
1295 .PP
1296
1297 .SS SONDY
1298 Hlavním syntaktickým konstruktem skriptovacího jazyka jsou sondy (probes). Sondy
1299 spojují abstraktní události s bloky příkazů a vytvářejí tak obslužné rutiny
1300 událostí. Obecná syntaxe je následující:
1301 .SAMPLE
1302 .BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " }
1303 .BR probe " PROBEPOINT [" , " PROBEPOINT] " "if (" CONDITION ") { " "[STMT ...]" " }"
1304 .ESAMPLE
1305 .PP
1306
1307 Události jsou určeny syntaxí nazývanou sondážní body (probe points). Existuje množství
1308 variant sondážních bodů. Některé jsou definovány překladačem a mnohé další jsou
1309 definovány v tapset skriptech jako přezdívky. Sondážní body mohou využívat
1310 zástupné znaky, být seskupovány, může být určováno jejich pořadí, či
1311 mohou být deklarovány jako volitelné. Více podrobností o syntaxi a sémantice
1312 sondážních bodů viz
1313
1314 .IR stapprobes (3stap).
1315
1316 .PP
1317 Obslužná rutina sondy se interpretuje relativně ke kontextu dané události. Pro
1318 události související s kernel kódem může tento kontext obsahovat
1319 .I proměnné
1320 definované ve
1321 .I zdrojovém kódu
1322 jádra. Takové "kontextové" proměnné jsou pak přístupné ve skriptu z prefixem "$".
1323 Jsou přístupné pouze pokud byly kompilátorem jádra zachovány navzdory
1324 optimalizacím. To je stejné omezení s jakým se potýká debugger když pracuje s
1325 optimalizovaným kódem. Navíc musí tyto objekty být v momentě vykonávání obslužné rutiny
1326 sondy přítomny přímo v nastránkované (in-paged) paměti, protože systemtap
1327 nesmí zapříčinit žádné dodatečné stránkování. Některé sondy mají velmi málo
1328 kontextových proměnných. Viz
1329 .IR stapprobes (3stap).
1330 .PP
1331 Proby mohou být doplněny
1332 .IR "podmínkou pro uzamčení" ,
1333 sestávající z jednoduchého booleovského výrazu. Sonda je "odemčená" (tedy
1334 neaktivní) vyhodnocuje-li se zamykací podmínka na false. V tomto stavu některé
1335 sondy snižují nebo zcela eliminují svoji režii, tedy nekonzumují systémové
1336 prostředky. Jakmile se zamykací podmínka vyhodnotí na true bude sonda
1337 .I brzy
1338 znovu uzamčena a její obslužná rutina začne brzy být opět volána když nastane
1339 příslušná událost. Přestože je zamykání rychlé, trvá nenulový čas, a některé
1340 události nemusejí být zachyceny. V případech kdy toto může představovat
1341 problém, je lepší zamykání sond nepoužívat.
1342 .PP
1343 Nové sondážní body lze definovat pomocí přezdívek (probe aliases). Definice
1344 přezdívky vypadá podobně jako definice sondy samotné, ale namísto aktivování
1345 sondy v daném místě pouze definují nové jméno - přezdívku pro již existující
1346 sondážní bod. Existují dva typy přezdívek: "prologue" a "epilogue", které jsou
1347 definovány pomocí "=" nebo resp. "+=".
1348 .PP
1349 Přezdívka typu "prologue" vznikne tak, že se blok příkazů, který následuje
1350 definici této přezdívky, přidá před sondu ke které se váže jako její prolog.
1351 Naproti tomu přezdíka typu "epilogue" vznikne tak, že blok příkazů, který
1352 následuje definici této přezdívky, se přidá za sondu ke které se váže jako její
1353 epilog. Například:
1354
1355 .SAMPLE
1356 probe syscall.read = kernel.function("sys_read") {
1357 fildes = $fd
1358 if (execname() == "init") next # přeskočit zbytek sondy
1359 }
1360 .ESAMPLE
1361 definuje nový sondážní bod.
1362 .nh
1363 .IR syscall.read ,
1364 .hy
1365 který se rozšiřuje na
1366 .nh
1367 .IR kernel.function("sys_read") ,
1368 .hy
1369 s daným příkazem jako prologem, což je výhodné k předdefinování některých
1370 proměnných pro danou přezdívku a/nebo pro přeskočení dané sondy v závislosti na
1371 podmínce. Naproti tomu
1372 .SAMPLE
1373 probe syscall.read += kernel.function("sys_read") {
1374 if (tracethis) println ($fd)
1375 }
1376 .ESAMPLE
1377 definuje nový sondážní bod s daným příkazem jako epilogem, což může být užitečné
1378 k provedení činností v závislosti na hodnotách proměnných nastavených
1379 uživatelem přezdívky. Poznamenejme, že v každém případě jsou příkazy v
1380 obslužné rutině přezdívky vykonávány za běhu, takže v danou chvíli zejména
1381 nedochází k vyhodnocování/substituci maker.
1382
1383 Přezdívku lze použít stejně jako vestavěnou sondu překladače.
1384 .SAMPLE
1385 probe syscall.read {
1386 printf("reading fd=%d\\n", fildes)
1387 if (fildes > 10) tracethis = 1
1388 }
1389 .ESAMPLE
1390
1391 .SS FUNKCE
1392 Systemtap skripty mohou definovat funkce. Ty mohou přijímat libovolný počet
1393 skalárních (celočíselných nebo řetězcových) parametrů, a vrací jednu skalární
1394 funkční hodnotu. Příklad funkce:
1395 .SAMPLE
1396 function thisfn (arg1, arg2) {
1397 return arg1 + arg2
1398 }
1399 .ESAMPLE
1400 Povšimněme si absence explicitních deklarací typů. Typy, jsou odvozeny
1401 (inferred) překladačem. Nicméně, pokud je to potřeba, může definice funkce
1402 zahrnovat explicitní deklarace návratového typu a/nebo typů argumentů. To je
1403 užitečné zejména pro vložené C funkce. V následujícím příkladě je automatické
1404 odvození typu nutné jen pro arg2 (řetězec):
1405
1406 .SAMPLE
1407 function thatfn:string (arg1:long, arg2) {
1408 return sprint(arg1) . arg2
1409 }
1410 .ESAMPLE
1411
1412 Funkce se mohou volat navzájem až do určitého limitu zanoření. Tento limit je
1413 definován makrem MAXNESTING ve vygenerovaném zdrojovém kódu modulu a pohybuje se
1414 okolo 10.
1415
1416 Funkce lze označit za privátní použitím klíčového slova "private". Tím se omezí
1417 jejich platnost soubor (tapset nebo uživatelský skript) ve kterém jsou
1418 definovány. Příklad:
1419 .SAMPLE
1420 private function three:long () { return 3 }
1421 .ESAMPLE
1422
1423 .SS TISK
1424 Existuje několik funkcí, se kterými překladač zachází neobvykle. Poznamenejme,
1425 že data jsou generována v jaderném modulu a před tiskem musí být přenesena do
1426 uživatelského prostoru. Tyto funkce formátují hodnoty pro pohodlný tisk do
1427 výstupního proudu systemtapu. Varianty funkce
1428
1429 .IR sprint*
1430 vracejí formátovaný řetězec namísto aby ho přímo vypisovaly.
1431 .TP
1432 .BR print ", " sprint
1433 Výpis jedné nebo více hodnot libovolného typu spojených dohromady.
1434 .TP
1435 .BR println ", " sprintln
1436 vypisují hodnoty stejně jako
1437 .IR print " a " sprint ,
1438 ale navíc připojují znak nového řádku.
1439 .TP
1440 .BR printd ", " sprintd
1441 Přijímají řetězcový oddělovač a dvě nebo více hodnot libovolného typu, a
1442 vytisknou je proložené tímto oddělovačem. Oddělovačem musí být řetězcový
1443 literál - konstanta.
1444 .TP
1445 .BR printdln ", " sprintdln
1446 Vytisknou hodnoty proložené oddělovačem podobně jako
1447 .IR printd " a " sprintd ,
1448 ale zároveň připojí znak konce řádku.
1449 .TP
1450 .BR printf ", " sprintf
1451 přijímají formátovací řetězec s množinou hodnot odpovídajících typů a všechny
1452 je vytisknou. Formátovacím řetězcem musí být řetězcový literál - konstanta.
1453 .PP
1454 Formátovací řetězec příkazu
1455 .IR printf
1456 je podobný jako v jazyce C s tím, že zde probíhá typová kontrola.
1457 .RS
1458 .TP
1459 %b
1460 Vypisuje binární blob dané hodnoty namísto ASCII textu. Specifikátor "width"
1461 určuje počet bajtů k vypsání. Validní specifikace jsou: %b %1b %2b %4b %8b.
1462 Výchozí je (%b), t.j. 8 bajtů.
1463 .TP
1464 %c
1465 Znak.
1466 .TP
1467 %d,%i
1468 Celé číslo se znaménkem.
1469 .TP
1470 %m
1471 Bezpečně čte paměť jádra na dané adrese, vrací její obsah. Volitelný
1472 specifikátor přesnosti (ne šířky pole) určuje počet bajtů k přečtení. Výchozí
1473 hodnota je 1 bajt. %10.4m vytiskne 4 bajty paměti v rámci 10 znaků širokého pole.
1474 .TP
1475 %M
1476 Stejné jako %m, ale výstup je hexadecimální. Minimální šířka výstupu je
1477 určitelná volitelným specifikátorem r - výchozí hodnota je 1 bajt (2
1478 hexadecimální znaky). %10.4M vytiskne 4 bajty paměti jako 8 hexadecimálních
1479 znaků v rámci 10 znaků širokého pole.
1480 .TP
1481 %o
1482 Oktalové číslo bez znaménka.
1483 .TP
1484 %p
1485 Ukazatel bez znaménka.
1486 .TP
1487 %s
1488 Řetězec.
1489 .TP
1490 %u
1491 Desítkové číslo bez znaménka.
1492 .TP
1493 %x
1494 Hexadecimální hodnota bez znaménka, malá písmena.
1495 .TP
1496 %X
1497 Hexadecimální hodnota bez znaménka, velká písmena.
1498 .TP
1499 %%
1500 Vypíše znak %.
1501 .RE
1502 .PP
1503 Znak
1504 .IR #
1505 zapíná alternativní formátování: Oktalovým číslům přidá prefix "0",
1506 hexadecimálním "0x", nebo "0X", a netisknutelným znakům v řetězci přidá prefix
1507 "escape" sekvence.
1508 .PP
1509 Příklady:
1510 .SAMPLE
1511 a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = \-1, id[a] = 1234, id[b] = 4567
1512 print("hello")
1513 Vypíše: hello
1514 println(b)
1515 Vypíše: bob\\n
1516 println(a . " is " . sprint(16))
1517 Vypíše: alice is 16
1518 foreach (name in id) printdln("|", strlen(name), name, id[name])
1519 Vypíše: 5|alice|1234\\n3|bob|4567
1520 printf("%c is %s; %x or %X or %p; %d or %u\\n",97,a,p,p,p,j,j)
1521 Vypíše: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; \-1 or 18446744073709551615\\n
1522 printf("2 bytes of kernel buffer at address %p: %2m", p, p)
1523 Vypíše: 2 byte of kernel buffer at address 0x1234abcd: <binary data>
1524 printf("%4b", p)
1525 Vypíše (these values as binary data): 0x1234abcd
1526 printf("%#o %#x %#X\\n", 1, 2, 3)
1527 Vypíše: 01 0x2 0X3
1528 printf("%#c %#c %#c\\n", 0, 9, 42)
1529 Vypíše: \\000 \\t *
1530 .ESAMPLE
1531
1532 .SS STATISTIKA
1533 Často je výhodné sbírat statistická data způsobem, který netrpí problémy s
1534 exkluzivním zamykáním globálních proměnných, kde se data udržují. Systemtap
1535 nabízí řešení ve formě speciálního operátoru pro uchovávání statistických dat a
1536 sady agregačních pseudofunkcí.
1537
1538 .PP
1539 Agregační operátor je
1540 .IR <<< ,
1541 a připomíná přiřazení, nebo operaci pro zápis do výstupního proudu známou z C++.
1542 Levý operand je skalární proměnná (nebo /skalární/ prvek pole - viz příklad
1543 níže), která musí být deklarována jako globální. Pravým operandem je číselný
1544 výraz. Význam je intuitivní: Přidej dané číslo na hromadu nad kterou bude
1545 později možno provádět statistické operace. Seznam funkcí pro extrakci
1546 statistických údajů je uveden níže. Příklad:
1547 .SAMPLE
1548 foo <<< 1
1549 stats[pid()] <<< memsize
1550 .ESAMPLE
1551 .PP
1552 Funkce pro extrakci statistiky jsou neobvyklé. Pro každý výskyt extrakční
1553 funkce pracující s daným identifikátorem zajistí překladač výpočet
1554 požadovaného statistického údaje. Statistický subsystém tedy funguje "na
1555 požádání" a výpočet probíhá v reálném čase na všech dostupných CPU.
1556 .PP
1557 Zde je seznam extrakčních funkcí. Prvním argumentem každé z nich je ta stejná
1558 l-hodnota, která byla použita pro akumulaci statistiky operátorem <<<.
1559 Extrakční funkce
1560 .IR @count(v) ", " @sum(v) ", " @min(v) ", " @max(v) ", " @avg(v) ", "
1561 @variance(v[, b]) počítají počet, sumu, minimum, maximum, aritmetický průměr,
1562 a střední kvadratickou odchylku přes všechny nashromážděné hodnoty. Funkčními
1563 hodnotami jsou celá čísla. Pole obsahující agregační data lze třídit a/nebo
1564 přes ně iterovat. Viz cyklus
1565 .BR foreach
1566 výše.
1567 .PP
1568
1569 Střední kvadratická odchylka se vyčísluje s použitím Welfordova algoritmu.
1570 Výpočty jsou prováděny v celočíselné aritmetice, proto mohou trpět nízkou
1571 přesností. Pro zlepšení přesnosti lze využít volitelný parametr b, tzv.
1572 bitový posun, s hodnotami od 0 (výchozí hodnota) do 62. Pro danou statistickou
1573 veličinu, resp. jí odpovídající globální proměnnou ve skriptu, lze použít pouze
1574 jednu jedinou hodnotu bitového posunu. Vyšší hodnoty bitového posunu zvyšují
1575 přesnost, ale zároveň zvyšují riziko přetečení.
1576
1577 .SAMPLE
1578 $ stap -e \\
1579 > 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x)) }'
1580 12
1581 $ stap -e \\
1582 > 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x,1)) }'
1583 2
1584 $ python3 -c 'import statistics; print(statistics.variance([1, 2, 3, 4, 5]))'
1585 2.5
1586 $
1587 .ESAMPLE
1588
1589 K přetečení může dojít zejména při interním násobení velkých čísel. Pokud k tomu
1590 dojde, může střední kvadratická odchylka vycházet záporná, což je normálně
1591 nepřípustné. Zvažte normalizování vašich dat. Přičtení, či odečtení konstanty
1592 ke všem hodnotám statistického vzorku nemění hodnotu střední kvadratické odchylky.
1593 Podělení všech hodnot statistického vzorku konstantou způsobí zmenšení střední
1594 kvadratické odchylky o čtverec dané konstanty.
1595
1596 \" the following is a more mathy rendering, but gnu nroff can't show them properly :-(
1597 .ig
1598
1599 If
1600 .EQ
1601 variance( v sub 1 , v sub 2 , ... , v sub N ) = V
1602 .EN
1603
1604 Then
1605 .EQ
1606 variance ( {v sub 1} over X , {v sub 2} over X, ... , {v sub N} over X ) = V over {X sup 2}
1607 .EN
1608
1609 and
1610 .EQ
1611 variance ( v sub 1 - Y, v sub 2 - Y, ... , v sub N - Y ) = V
1612 .EN
1613
1614 ..
1615
1616 Dostupné jsou též histogramy. Například
1617 .I @hist_linear(v,start,stop,interval)
1618 reprezentuje lineární histogram od "start" do "stop" s inkrementem "interval".
1619 Inkrement musí být kladný. Podobně
1620 .I @hist_log(v)
1621 představuje binárně logaritmický histogram. Histogram lze vytisknout některou
1622 z rodiny
1623 .I print
1624 funkcí. Výsledkem je ASCII-art. Příklad:
1625
1626 .SAMPLE
1627 probe timer.profile {
1628 x[1] <<< pid()
1629 x[2] <<< uid()
1630 y <<< tid()
1631 }
1632 global x // pole
1633 global y // skalár
1634 probe end {
1635 foreach ([i] in x @count+) {
1636 printf ("x[%d]: avg %d = sum %d / count %d\\n",
1637 i, @avg(x[i]), @sum(x[i]), @count(x[i]))
1638 println (@hist_log(x[i]))
1639 }
1640 println ("y:")
1641 println (@hist_log(y))
1642 }
1643 .ESAMPLE
1644
1645 .SS PŘETYPOVÁNÍ
1646 Jakmile se ukazatel uloží do celočíselné proměnné v rámci systemtap skriptu,
1647 překladač ztrácí informaci o typu, která je potřebná k dereferencování.
1648 (viz KONTEXTOVÉ PROMĚNNÉ man stránky
1649 .IR stapprobes (3stap)) .
1650 Použitím operátoru
1651 .I @cast()
1652 sdělujeme kompilátoru, jak má interpretovat takové číslo jakožto typovaný
1653 ukazatel. Příklad:
1654 .SAMPLE
1655 @cast(p, "type_name"[, "module"])\->member
1656 .ESAMPLE
1657 .PP
1658 Takto bude
1659 .I p
1660 interpretován jako ukazatel do struktury/unionu
1661 .I type_name
1662 a dereferencovat
1663 .I member .
1664 Lze připojit další
1665 .IR \->subfield
1666 a dereferencovat tak další úrovně. Poznamenejme, že pro přímé dereferencování
1667 ukazatele se doporučuje použít funkcí {kernel,user}_{char,int,...}($p). Více
1668 v sekci stapfuncs(5).
1669
1670 .BR
1671 POZNÁMKA:
1672 stejný operátor
1673 .IR \->
1674 se používá jak pro přímý odkaz na člena, tak pro dereferenci ukazatele.
1675 Systemtap automaticky interpretuje tuto dvojakost.
1676 Volitelná složka
1677 .I module
1678 informuje překladač, kde má hledat informaci o daném typu.
1679 .I module
1680 lze uvést vícekrát jako seznam s oddělovačem
1681 .IR : .
1682 Pokud
1683 .I module
1684 není explicitně určen, budou pro jeho určení využity ladicí
1685 informace, nebo bude nastaven na "kernel" pro funkce a všechny ostatní typy
1686 sond.
1687 .PP
1688 Překladač může vytvořit svůj vlastní modul s informacemi o typech odvozením z
1689 hlavičkových souborů uzavřených ve špičatých závorkách v případě, že ladicí
1690 informace nejsou k dispozici. Hlavičkovým souborům jádra je třeba přidat
1691 řetězec "kernel" jako předponu. Ostatní hlavičkové soubory budou zpracovány s
1692 výchozími volbami kompilátoru. Lze specifikovat více hlavičkových souborů za
1693 sebou pro vyřešení závislostí.
1694
1695 .SAMPLE
1696 @cast(tv, "timeval", "<sys/time.h>")\->tv_sec
1697 @cast(task, "task_struct", "kernel<linux/sched.h>")\->tgid
1698 @cast(task, "task_struct",
1699 "kernel<linux/sched.h><linux/fs_struct.h>")\->fs\->umask
1700 .ESAMPLE
1701 Hodnoty získané operátorem
1702 .BR @cast
1703 lze přehledně vytisknout (pretty-print) připojením operátoru
1704 .BR $ " a " $$
1705 jak je popsáno v sekci KONTEXTOVÉ PROMĚNNÉ man stránky
1706 .IR stapprobes (3stap).
1707
1708 .PP
1709 V guru režimu (-g) umožňuje překladač také přiřadit novou hodnotu
1710 dereferencovaným ukazatelům.
1711 .PP
1712 Přetypování je také užitečné v případě
1713 .I void*
1714 členů jejichž typ lze určit až za běhu. Příklad:
1715 .SAMPLE
1716 probe foo {
1717 if ($var\->type == 1) {
1718 value = @cast($var\->data, "type1")\->bar
1719 } else {
1720 value = @cast($var\->data, "type2")\->baz
1721 }
1722 print(value)
1723 }
1724 .ESAMPLE
1725
1726 .SS EMBEDDED C
1727 V guru režimu přijímá překladač vložený C kód v uživatelských
1728 skriptech. Takový kód je uzavřen mezi značkami
1729 .IR %{
1730 a
1731 .IR %}
1732 a je doslovně, bez analýzy, vložen do vnější úrovně vygenerovaného kódu
1733 systemtap modulu. Protože je vložen do vnější úrovně, je možné takto definovat
1734 .IR #include
1735 direktivy a různé pomocné definice použitelné ve zbytku kódu.
1736 .PP
1737 Dalším místem, kde je vložené C povoleno, je tělo funkce. V tomto případě
1738 bude tělo systemtap funkce doslovně tvořeno vloženým C kódem uzavřeným mezi
1739 značky
1740 .IR %{ " a " %} .
1741 Takto vložený C kód může vykonávat libovolnou rozumnou a bezpečnou činnost.
1742 Existuje množství nedokumentovaných a komplexních omezení ohledně atomicity,
1743 souběžnosti, spotřeby zdrojů a časových omezení, takže jde o pokročilou
1744 techniku.
1745 .PP
1746 Paměťová umístění vyhrazená pro vstupní a výstupní hodnoty jsou zpřístupněna
1747 pomocí maker
1748 .IR STAP_ARG_*
1749 a
1750 .IR STAP_RETVALUE .
1751 Chyby lze signalizovat pomocí STAP_ERROR, výstup pomocí STAP_PRINTF a
1752 návratovou hodnotu lze předat prostřednictvím STAP_RETURN. Zde je několik
1753 příkladů:
1754
1755 .SAMPLE
1756 function integer_ops (val) %{
1757 STAP_PRINTF("%d\\n", STAP_ARG_val);
1758 STAP_RETVALUE = STAP_ARG_val + 1;
1759 if (STAP_RETVALUE == 4)
1760 STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE);
1761 if (STAP_RETVALUE == 3)
1762 STAP_RETURN(0);
1763 STAP_RETVALUE ++;
1764 %}
1765 function string_ops (val) %{
1766 strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
1767 strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN);
1768 if (strcmp (STAP_RETVALUE, "three-two-one"))
1769 STAP_RETURN("parametr měl být be three-two-");
1770 %}
1771 function no_ops () %{
1772 STAP_RETURN(); /* funkce bez návratové hodnoty */
1773 %}
1774 .ESAMPLE
1775 Typy funkčních hodnot a typ návratové hodnoty odvodí překladač ze způsobu
1776 volání dané funkce. Před vytvářením vlastních vložených C funkcí je vhodné
1777 prostudovat zdrojový kód, který překladač generuje pro běžné funkce
1778 skriptovacího jazyka a tím se inspirovat.
1779
1780 .PP
1781 Poslední místo, kde je vložené C povoleno, je r-hodnota ve výrazu.
1782 V tomto případě se C-kód uzavře mezi značky
1783 .IR %{ " a " %}
1784 a interpretuje se jako běžná hodnota výrazu. Předpokládá se pak, že jde o 64
1785 bitové číslo se znaménkem, ovšem pokud se použije značka
1786 .I /* string */,
1787 bude hodnota výrazu interpretována jako řetězec. Příklad:
1788 .SAMPLE
1789 function add_one (val) {
1790 return val + %{ 1 %}
1791 }
1792 function add_string_two (val) {
1793 return val . %{ /* string */ "two" %}
1794 }
1795 .ESAMPLE
1796 .PP
1797 K nastavení bezpečnosti a optimalizace lze použít následující značky:
1798 .TP
1799 .I /* pure */
1800 znamená, že C kód nemá žádné vedlejší efekty a může být v rámci optimalizace
1801 zcela zahozen pokud nemá vazby na zbytek kódu.
1802 .TP
1803 .I /* stable */
1804 znamená, že C kód má vždy stejnou hodnotu (při vyvolání v rámci libovolné obslužné rutiny
1805 sondy), takže opakovaná volání mohou být nahrazena zapamatovanou hodnotou.
1806 Takové funkce nesmí přijímat parametry a musí být
1807 .IR /* pure */ .
1808 .TP
1809 .I /* unprivileged */
1810 znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní uživatelé.
1811 .TP
1812 .I /* myproc\-unprivileged */
1813 znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní
1814 uživatelé, ovšem jen při analýze svých vlastních uživatelských procesů.
1815 .TP
1816 .I /* guru */
1817 znamená, že C kód je tak nebezpečný, že vyžaduje použití guru režimu
1818 .IR \-g .
1819 .TP
1820 .I /* unmangled */
1821 ve vložené C funkci zpřístupní zastaralou (pre-1.8) syntaxi pro přístup k
1822 funkčním parametrům. V tomto případě lze uvnitř funkce kromě
1823 .I STAP_ARG_foo
1824 a
1825 .I STAP_RETVALUE
1826 použít také
1827 .I THIS->foo
1828 a
1829 .I THIS->__retvalue .
1830 .TP
1831 .I /* unmodified-fnargs */
1832 ve vložené C funkci znamená, že parametry nejsou uvnitř těla funkce měněny.
1833 .TP
1834 .I /* string */
1835 ve vložené C funkci znamená, že výraz má typ
1836 .I const char *
1837 a mělo by s ním být nakládáno jako s řetězcovou hodnotou namísto numerické (což
1838 je výchozí chování).
1839
1840 .SS BUILT-INS
1841 Skripty instalované v umístění definovaném ve
1842 .IR stappaths (7)
1843 poskytují množství vestavěných sondážních bodů. Ty jsou popsány v man stránce
1844 .IR stapprobes (3stap) .
1845
1846 .SH ZPRACOVÁNÍ SKRIPTU
1847 Systemtap zpracovává skript v pěti procesních fázích: "parse", "elaborate",
1848 "translate", "compile" a "run". Překladač zahájí fázi 1 lexikální analýzou
1849 uživatelského skriptu spolu se všemi tapset skripty (což jsou soubory s příponou
1850 .IR *.stp )
1851 nalezenými v tapset adresáři. Adresáře vyjmenované prostřednictvím
1852 .BR \-I
1853 jsou následně zpracovány také, a to v guru režimu. Adresářová struktura se
1854 prohledává do hloubky. Některé podadresáře jsou specifické pro verzi jádra
1855 (volba
1856 .BR \-R
1857 ), a podle ní jsou (nebo nejsou) prohledávány, takže skripty specifičtější pro
1858 danou verzi jádra mohou předefinovat své méně specifické protějšky. Například pro
1859 verzi jádra
1860 .IR 2.6.12\-23.FC3
1861 by byly prohledávány následující adresáře:
1862 .IR 2.6.12\-23.FC3/*.stp ,
1863 .IR 2.6.12/*.stp ,
1864 .IR 2.6/*.stp ,
1865 a nakonec
1866 .IR *.stp
1867 v tomto pořadí. Pokud překlad skončí na konci fáze 1 (-p1), pak překladač na
1868 standardní výstup vypíše derivační strom (parse tree).
1869 .PP
1870 Ve fázi 2 překladač analyzuje vstupní skript, aby vyhodnotil symboly a datové
1871 typy. Odkazy na proměnné, funkce a přezdívky, které se nepodaří vyhodnotit
1872 lokálně, se vyhodnotí proti tapset skriptům. Pokud je určitý symbol nalezen v
1873 tapset skriptu, pak daný tapset bude celý přidán do fronty pro zpracování
1874 překladačem. Tento iterativní proces skončí jakmile jsou vyhodnoceny všechny
1875 symboly s využitím dané podmnožiny tapset skriptů.
1876 .PP
1877 Dále se ověří validnost sondážních bodů. Sondy, které se odkazují k umístěním
1878 ve zdrojovém kódu ("synchronní sondážní body") vyžadují, aby byly nainstalovány
1879 příslušné ladicí informace. V obslužných rutinách sond se naleznou cílové
1880 proměnné (ty, které začínají znakem "$") a dekódují se jejich "run-time"
1881 lokace.
1882
1883 .PP
1884 Dále se všechny sondy a funkce optimalizují. Cílem je odstranit zbytečné
1885 proměnné, výrazy a funkce, které nemají vedlejší účinky. U vložených C funkcí
1886 se předpokládá, že mají vedlejší účinky pokud ovšem neobsahují kouzelnou značku
1887 .BR /*\ pure\ */ .
1888 Vzhledem k tomu, že optimalizace mohou způsobit latentní chyby jako je
1889 například typová nekompatibilita, nebo neplatné kontextové proměnné, může být v
1890 některých případech užitečné optimalizace vypnout přepínačem
1891 .BR \-u .
1892 .PP
1893 Nakonec se z kontextu odvodí datové typy proměnných, funkcí, parametrů, polí a
1894 indexů. Ukončení překladu po fázi 2 (-p2) způsobí vypsání seznamu všech sond,
1895 funkcí a proměnných spolu s jejich odvozenými typy. Nekonzistentní nebo
1896 neodvoditelné typy způsobí chybu překladu.
1897
1898 .PP
1899 Ve fázi 3 překladač zapíše vygenerovaný C kód a vytvoří
1900 .IR Makefile
1901 který slouží k jeho přeložení do podoby jaderného modulu. Tyto soubory
1902 budou umístěny v dočasném adresáři. Zastavení překladače v této fázi (-p3)
1903 způsobí vypsání C souboru na standardní výstup.
1904
1905 .PP
1906 Ve fázi 4 překladač vyvolá jaderný "build systém", aby sestavil systemtap
1907 modul. Při tom se v daném dočasném adresáři volá příkaz
1908 .IR make .
1909 K úspěšnému provedení tohoto kroku je třeba, aby byl nainstalován "build systém"
1910 jádra, tj. hlavičkové soubory, config a Makefile soubory a to v obvyklém
1911 umístění
1912 .IR /lib/modules/VERSION/build .
1913 Zastavení překladače v této fázi (-p4) může být užitečné, pokud chceme modul
1914 archivovat. Je to také poslední šance zastavit systemtap před zavedením a
1915 spuštěním modulu.
1916 .PP
1917 Ve fázi 5 překladač zavolá pomocný program
1918 .I staprun
1919 a předá mu vzniklý systemtap modul. Program staprun zavede modul do jádra,
1920 spustí jej a zajišťuje komunikaci s ním dokud činnost modulu neskončí.
1921 Jakákoliv chyba běhu, která se vyskytne v obslužných rutinách sond, jako např.
1922 vyčerpání dostupné paměti, dělení nulou, příliš hluboké zanoření, nebo
1923 překročení "run-time" limitů, způsobí měkkou chybu (soft error). Pokud počet
1924 měkkých chyb překročí MAXERRORS, zastaví se všechny sondy (kromě těch, které
1925 obsluhují chyby), a zastaví se sezení. Nakonec
1926 .I staprun
1927 odstraní modul z jádra a provede úklid.
1928
1929 .SS NEOBVYKLÉ UKONČENÍ
1930
1931 Je dobré neukončovat stap proces násilím, například prostřednictvím signálu
1932 SIGKILL, protože proces stapio (potomek procesu stap) a systemtap modul by se
1933 nemusely korektně ukončit. Pokud se to přecejen stane, pošlete všem zbývajícím
1934 stapio procesům SIGTERM nebo SIGINT a použijte rmmod pro odstranění systemtap
1935 modulu z jádra.
1936
1937 .SH PŘÍKLADY
1938 Viz
1939 .IR stapex (3stap)
1940 , kde se nachází několik krátkých příkladů, nebo viz adresář "examples" v RPM
1941 balíčcích "systemtap-client", či "systemtap-testsuite", kde se nachází rozsáhlá
1942 sbírka příkladů. Viz
1943 .IR stappaths (7stap)
1944 pro podrobný popis konkrétních umístění. Příklady jsou také zveřejněny na
1945 webové stránce projektu systemtap.
1946
1947 .SH CACHE
1948 Překladač systemtapu ukládá do cache výstup fáze 3 (tj. vygenerovaný C kód) a
1949 výstup fáze 4 (tj. zkompilovaný jaderný modul) pokud tyto fáze skončí bez chyb.
1950 Obsah cache se použije pokud se znovu překládá stejný skript a za předpokladu,
1951 že platí stejné podmínky (verze jádra, verze systemtapu atp.). Cache se
1952 nachází v adresáři
1953 .I $SYSTEMTAP_DIR/cache .
1954 Velikost cache lze omezit umístěním souboru
1955 .I cache_mb_limit
1956 do cache adresáře, přičemž tento soubor obsahuje ASCII číselnou hodnotu
1957 limitu, která vyjadřuje velikost cache v MiB. Pokud tento soubor neexistuje,
1958 vytvoří se nový s výchozí hodnotou 256. Jde o měkký limit v tom smyslu, že
1959 cache bude promazána až po určité době. Dočasně tedy může velikost cache
1960 překročit stanovený limit. Zmíněnou periodu je možno nastavit
1961 prostřednictvím souboru
1962 .I cache_clean_interval_s
1963 umístěného opět v cache adresáři. Předpokládá se, že tento soubor obsahuje
1964 ASCII celé číslo vyjadřující časový interval pro promazávání cache v sekundách.
1965 Pokud tento soubor neexistuje, vytvoří se nový s výchozí hodnotou 300.
1966
1967 .SH BEZPEČNOST A OCHRANA SOUKROMÍ
1968
1969 .PP
1970 Systemtap může být použit jako mocný administrativní nástroj. Může zpřístupnit
1971 privátní uživatelské informace v rámci interních jaderných struktur. To se
1972 netýká
1973 .BR dyninst
1974 runtime, viz
1975 .I ALTERNATIVNÍ RUNTIME .
1976
1977 Překladač zajišťuje dodržování mnoha různých bezpečnostních omezení během
1978 kompilace a běhu modulu. Snaží se zajistit, aby žádná sonda neběžela příliš
1979 dlouho, aby nealokovala příliš mnoho paměti, neprováděla nebezpečné operace, nebo
1980 nežádoucím způsobem neovlivňovala systém. Při práci s globálními proměnnými se
1981 využívají zámky pro čtení a zápis, aby nedocházelo k chybám při souběhu.
1982 Pravidelně dochází k testu na deadlocky. Pro zjištění nepřiměřeného použití
1983 zámků lze použít přepínač
1984 .BR \-t .
1985 Experimentování se skripty je tedy v zásadě bezpečné.
1986 .BR Guru" "režim
1987 .B \-g
1988 umožňuje administrátorům obejít většinu bezpečnostních opatření a umožnit tak
1989 invazivní zásahy a změny stavu systému, použít vložené C a obecně zvýšit
1990 riziko průšvihu. Za normálních okolností je pro všechny moduly aktivní ochrana
1991 proti přetížení. Tu lze vypnout přepínačem
1992 .BR \-\-suppress\-time\-limits.
1993
1994 Chyby zachycené při běhu za normálních okolností vedou k čistému ukončení
1995 skriptu s chybovou hláškou. Přepínač
1996 .BR \-\-suppress\-handler\-errors
1997 umožňuje zcela ignorovat měkké chyby, takže ani po nastřádání jejich většího
1998 počtu nedojde k ukončení skriptu.
1999
2000
2001 .SS OPRÁVNĚNÍ
2002 Aby bylo možné spustit systemtap modul v rámci výchozí kernel runtime, musí
2003 uživatel splnit jednu z následujících podmínek:
2004
2005 .IP \(bu 4
2006 být root.
2007 .IP \(bu 4
2008 být členem skupin
2009 .I stapdev
2010 a
2011 .I stapusr
2012 .IP \(bu 4
2013 být členem skupin
2014 .I stapsys
2015 a
2016 .I stapusr
2017 ; nebo
2018 .IP \(bu 4
2019 být členem skupiny
2020 .I stapusr .
2021 .PP
2022 Uživatel root, nebo uživatel, který je členem skupin
2023 .I stapdev
2024 a
2025 .I stapusr
2026 , může přeložit a spustit libovolný systemtap skript.
2027 .PP
2028 Uživatel, který je členem skupin
2029 .I stapsys
2030 a
2031 .I stapusr,
2032 může použít předem připravené systemtap moduly za následujících podmínek:
2033 .IP \(bu 4
2034 Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap
2035 kompilačním serverem, který podepsal modul klientovi, který použil volbu
2036 \fI\-\-privilege\fR. Viz
2037 .IR stap\-server (8) .
2038 .IP \(bu 4
2039 Modul byl sestaven s použitím jedné z voleb \fI\-\-privilege=stapsys\fR nebo
2040 \fI\-\-privilege=stapusr\fR.
2041
2042 .PP
2043 Členové pouze skupiny
2044 .I stapusr
2045 mohou používat jen předem připravené moduly za následujících podmínek:
2046 .IP \(bu 4
2047 Modul je umístěn v adresáři
2048 /lib/modules/VERSION/systemtap. Tento adresář musí být vlastněn uživatelem
2049 root a nesmí být otevřený pro zápis všem.
2050 .PP
2051 nebo
2052 .IP \(bu 4
2053 Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap
2054 kompilačním serverem, který podepsal modul klientovi, který použil volbu
2055 \fI\-\-privilege\fR. Podrobnější informace viz
2056 .IR stap\-server (8) .
2057 .IP \(bu 4
2058 Modul byl přeložen s volbou \FI\-\-privilege=stapusr\fR.
2059 .PP
2060 Jaderné moduly vygenerované programem
2061 .I stap
2062 se zavádějí do jádra a spouštějí pomocí programu
2063 .IR staprun .
2064 Staprun je součástí systemtap balíčku určeného k zavádění a
2065 odstraňování modulů (za daných podmínek). Slouží také k přenosu dat
2066 mezi systemtap modulem a uživatelelm. Protože
2067 .IR staprun
2068 neprovádí žádné bezpečnostní kontroly modulu se kterým pracuje, bylo by od
2069 administrátora systému nemoudré přidat nedůvěryhodného uživatele do skupiny
2070 .I stapdev
2071 nebo
2072 .I stapusr .
2073
2074 .SS SECUREBOOT
2075
2076 Pokud má systém v rámci UEFI firmware zapnutý SecureBoot, všechny jaderné
2077 moduly musejí být kryptograficky podepsány. (Některá jádra dovolují vypnout
2078 SecureBoot za běhu kombinací kláves SysRq-X. Poté nemusí být moduly podepsané.)
2079 Kompilační server systemtapu může podepisovat moduly klíčem MOK (Machine Owner
2080 Key) který sdílí s daným systémem. Pro více informací viz následující wiki:
2081
2082 .PP
2083 .RS
2084 .nh
2085 .BR https://sourceware.org/systemtap/wiki/SecureBoot
2086 .hy
2087 .RE
2088
2089 .SS LIMITY NA ZDROJE
2090 Mnoho omezení pro využívání prostředků systému se nachází ve formě maker ve
2091 vygenerovaném C kódu systemtap modulu. Ty lze předefinovat prostřednictvím
2092 přepínače
2093 .BR \-D .
2094 Seznam zmíněných maker:
2095 .TP
2096 MAXNESTING
2097 Maximální počet zanořených funkčních volání. Výchozí hodnota se určuje při
2098 analýze skriptu. Skripty založené na rekurzi obdrží 10 bonusových slotů.
2099 .TP
2100 MAXSTRINGLEN
2101 Maximální délka řetězce. Výchozí hodnota je 128 znaků.
2102 .TP
2103 MAXTRYLOCK
2104 Maximální počet iterací při čekání na uvolnění zámku na globální proměnné před
2105 tím, než se vyhlásí deadlock a sonda se přeskočí. Výchozí hodnota je 1000
2106 iterací.
2107 .TP
2108 MAXACTION
2109 Maximální počet příkazů, které mohou být vykonány během jednoho hitu sondy (s
2110 vypnutými přerušeními). Výchozí hodnota je 1000.
2111
2112 .TP
2113 MAXACTION_INTERRUPTIBLE
2114 Maximální počet příkazů, které mohou být vykonány během jedné aktivace (probe
2115 hit) sondy, která se provádí s povolenými přerušeními. (jako např. sondy begin
2116 a end). Výchozí hodnota je 10 * MAXACTION.
2117 .TP
2118 MAXBACKTRACE
2119 Maximální počet zásobníkových rámců, které budou zpracovány při výpisu
2120 backtrace. Relevantní tapset je [u]context-unwind.stp, a výchozí hodnota je
2121 20.
2122 .TP
2123 MAXMAPENTRIES
2124 Maximální počet řádků v každém jednom globálním poli. Výchozí hodnota je 2048.
2125 Jednotlivá pole mohou být deklarována s odlišným limitem. Příklad:
2126 .SAMPLE
2127 global big[10000],little[5]
2128 .ESAMPLE
2129 nebo je možno využít modifikátoru
2130 .IR %
2131 , čímž se zapne array-wrapping (nahrazování "starých" prvků) jako v následujícím
2132 příkladu:
2133
2134 .SAMPLE
2135 global big%
2136 .ESAMPLE
2137
2138 Viz sekce o polích.
2139 .TP
2140 MAXERRORS
2141 Maximální množství měkkých chyb, které ještě nezpůsobí ukončení skriptu.
2142 Výchozí hodnotou je 0, tedy skript skončí při první měkké chybě. Poznamenejme,
2143 že
2144 .B \-\-suppress\-handler\-errors
2145 tento limit vypíná.
2146 .TP
2147 MAXSKIPPED
2148 Maximální počet přeskočených sond, který ještě nevede k ukončení skriptu.
2149 Výchozí hodnotou je 100. Pozn., že systemtap lze spustit s přepínačem \-t
2150 (timing), který zobrazí podrobnosti ohledně počtu přeskočených sond. Při
2151 použití \-DINTERRUPTIBLE=1 se nebudou brát v potaz sondy přeskočené kvůli
2152 re-entranci. Dále poznamenejme, že
2153 .B \-\-suppress\-handler\-errors
2154 vypíná i tento limit.
2155 .TP
2156 MINSTACKSPACE
2157 Minimální množství volného místa na zásobníku jádra dostatečné pro start sondy.
2158 Výchozí hodnota 1024 bajtů. Tato hodnota by měla být dostačující pro vlastní
2159 potřebu obslužné rutiny včetně malé rezervy.
2160
2161 .TP
2162 MAXUPROBES
2163 Maximální množství současně zamčených uživatelských sond (uprobes). Výchozí
2164 hodnota je o něco málo vyšší, než počet uživatelských sond ve skriptu. Tato
2165 hodnota musí být relativně velká, protože jednotlivé uživatelské sondy (každá z
2166 nich okupuje přibližně 46 bajtů), se alokují pro každý proces a pro každou
2167 odpovídající sondu ve skriptu.
2168
2169 .TP
2170 STP_MAXMEMORY
2171 Maximální velikost paměti (v kilobajtech), kterou je systemtap modul oprávněn
2172 použít. Výchozí hodnota je neomezená. Limit zahrnuje velikost modulu
2173 samotného plus dodatečné alokace. Zahrnuty jsou jen přímé alokace provedené
2174 systemtap runtime. Nepřímé alokace, které provádějí např, "kprobes", "uprobes",
2175 atd., nejsou započteny.
2176
2177 .TP
2178 STP_OVEROAD_THRESHOLD, STP_OVERLOAD_INTERVAL
2179 Maximální počet cyklů, které lze strávit v sondách za daný čas (též vyjádřený v
2180 cyklech). Při překročení této podmínky dojde k přetížení a skript se zastaví.
2181 Výchozí hodnoty jsou 5e+8 a 1e+9, což odpovídá max. 50% povolenému vytížení.
2182
2183 .TP
2184 STP_PROCFS_BUFSIZE
2185 Velikost procfs bufferů pro čtení (v bajtech). Výchozí hodnota je
2186
2187 .IR MAXSTRINGLEN .
2188 Tento limit lze nastavit specificky pro jednotlivé sondy pomocí syntaxe
2189 .I .maxsize(MAXSIZE) .
2190 .PP
2191 Pokud skript obsahuje sondy vázané na přerušení, je možné, že k přerušení dojde
2192 tak často, že handler daného přerušení ještě nedoběhne zatímco dojde k dalšímu
2193 přerušení. V tomto případě bude obslužná rutina přeskočena, aby se zamezilo
2194 reentranci. Tento problém lze obejít použitím
2195 .BR \-DINTERRUPTIBLE=0 k odstínění běžící obslužné rutiny od daného přerušení.
2196 Tento přístup přináší jistou režii, ale v běžných případech zamezí reentranci.
2197 Nicméně, sondy v NMI handlerech a v samotném procesu stap, mohou stále být
2198 přeskočeny, aby se zamezilo reentranci.
2199
2200 .PP
2201 Vznikne-li problém při běhu programu
2202 .IR stap " nebo " staprun
2203 když už sondy běží, je možné bezpečně zabít oba tyto uživatelské procesy a
2204 odstranit systemtap modul pomocí
2205 .IR rmmod .
2206 Část výstupu se tak nicméně může ztratit.
2207
2208 .SH NEPRIVILEGOVANÍ UŽIVATELÉ
2209
2210 .PP
2211 Systemtap umožňuje přístup k interním datům jádra a tedy potenciálně k
2212 soukromým datům uživatele. Z tohoto důvodu je plný přístup k systemtapu omezen
2213 na uživatele root a na uživatele, kteří jsou členy skupin stapdev a stapusr.
2214
2215 Nicméne omezená sada funkcí systemtapu může být dostupná důvěryhodným
2216 neprivilegovaným uživatelům. Tito uživatelé jsou členy pouze skupiny stapusr
2217 plus případně skupiny stapsys.
2218
2219 Tito uživatelé mohou zavést do jádra předem připravený modul, který byl podepsán
2220 důvěryhodným kompilačním serverem. Viz popis voleb \fI\-\-privilege\fR a
2221 \fI\-\-use\-server\fR. Viz také \fIREADME.unprivileged\fR mezi zdrojovými
2222 soubory systemtapu. Tam je mj. popsáno jak nastavit důvěryhodný kompilační server.
2223
2224 Omezení která plynou z volby \fI\-\-privilege=stapsys\fR mají zabránit
2225 neprivilegovaným uživatelům v
2226
2227 .RS
2228 .IP \(bu 4
2229 záměrném poškozování systému.
2230 .RE
2231
2232 Omezení, která plynou z volby \fI\-\-privilege=stapusr\fR mají zabránit
2233 neprivilegovaným uživatelům v
2234
2235 .RS
2236 .IP \(bu 4
2237 záměrném poškozování systému.
2238 .IP \(bu 4
2239 získání přístupu k neveřejným / soukromým informacím.
2240 .IP \(bu 4
2241 snižování výkonu procesů vlastněných jinými uživateli systému. Určitému vlivu
2242 na výkon celého systému nelze zabránit, neboť sondy neprivilegovaného uživatele
2243 budou v příslušný čas aktivní. Nicméně hlavním cílem zde je, aby
2244 neprivilegovaný uživatel nežádoucím nezpůsobem zasahoval do procesů jiných
2245 uživatelů.
2246
2247 .RE
2248
2249 .SS OMEZENÍ NA SONDY
2250 Člen skupin stapusr a stapsys má přístup ke všem sondám.
2251 .PP
2252 Člen pouze skupiny stapusr může použít následující sondy:
2253 .RS
2254 .IP \(bu 4
2255 begin, begin(n)
2256 .IP \(bu 4
2257 end, end(n)
2258 .IP \(bu 4
2259 error(n)
2260 .IP \(bu 4
2261 never
2262 .IP \(bu 4
2263 process.*, s tím, že cílový proces je jeho vlastní.
2264 .IP \(bu 4
2265 timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)*
2266 .IP \(bu 4
2267 timer.hz(n)
2268 .RE
2269
2270 .SS OMEZENÍ SKRIPTOVACÍHO JAZYKA
2271 Následující vlastnosti skriptovacího jazyka jsou pro neprivilegovaného
2272 uživatele nedostupné:
2273
2274 .RS
2275 .IP \(bu 4
2276 jakákoliv funkcionalita podmíněná guru režimem (-g).
2277 .IP \(bu 4
2278 vložený C kód.
2279 .RE
2280
2281 .SS RUNTIME OMEZENÍ
2282 Neprivilegovaných uživatelů se týkají také následující omezení runtime:
2283 .RS
2284 .IP \(bu 4
2285 Lze použít jen výchozí runtime kód (viz \fI-R\fR).
2286 .RE
2287
2288 Na členy pouze skupiny stapusr se vztahují dodatečná omezení:
2289 .RS
2290 .IP \(bu 4
2291 Analýza procesů vlastněných jinými uživateli není dovolena.
2292 .IP \(bu 4
2293 Přístup do paměti jádra není dovolen ani pro zápis, ani pro čtení.
2294 .RE
2295
2296 .SS OMEZENÍ NA VOLBY PŘÍKAZOVÉ ŘÁDKY
2297 Některé volby příkazové řádky poskytují přístup k funkcionalitě, která nesmí být
2298 přístupná žádnému neprivilegovanému uživateli. Konkrétně
2299
2300 .RS
2301 .IP \(bu 4
2302 Nesmí nastavit \-g .
2303 .IP \(bu 4
2304 Následující volby nesmějí být použity klientem kompilačního serveru:
2305 .SAMPLE
2306 \-a, \-B, \-D, \-I, \-r, \-R
2307 .ESAMPLE
2308 .RE
2309
2310 .SS OMEZENÍ NA PROMĚNNÉ PROSTŘEDÍ
2311 Neprivilegovaní uživatelé nesmějí nastavit následující proměnné prostředí:
2312 .SAMPLE
2313 SYSTEMTAP_RUNTIME
2314 SYSTEMTAP_TAPSET
2315 SYSTEMTAP_DEBUGINFO_PATH
2316 .ESAMPLE
2317
2318 .SS OMEZENÍ NA TAPSETY
2319 Obecně jsou tapset funkce přístupné členům skupiny stapusr pokud nepřistupují k
2320 informacím, které by neměl právo získat libovolný uživatelský program běžící s
2321 identitou daného uživatele.
2322
2323 Existují dvě skupiny tapset funkcí pro neprivilegované uživatele. První
2324 kategorie sestává z funkcí, které mohou použít všichni uživatelé, jako
2325 napřiklad:
2326 .SAMPLE
2327 cpu:long ()
2328 exit ()
2329 str_replace:string (prnt_str:string, srch_str:string, rplc_str:string)
2330 .ESAMPLE
2331
2332
2333 Druhou skupinou jsou tzv.
2334 .I myproc-unprivileged
2335 funkce, které mohou sbírat informace pouze o procesech, které daný uživatel
2336 vlastní. Skripty, které mají používat myproc-unprivileged funkce musí testovat
2337 \fIis_myproc()\fR a volat takové funkce jen když výsledek je 1. Skript se
2338 ihned ukončí, pokud tato podmínka nebude splněna. Přiklady
2339 .I myproc-unprivileged
2340 funkcí:
2341 .SAMPLE
2342 print_usyms (stk:string)
2343 user_int:long (addr:long)
2344 usymname:string (addr:long)
2345 .ESAMPLE
2346
2347 Pokud se uživatel patřící pouze do skupiny stapusr pokusí použít tapset funkci,
2348 která nespadá do žádné ze zmíněných dvou kategorií, dojde k chybě při
2349 kompilaci.
2350
2351 .SH ALTERNATIVNÍ RUNTIME BACKENDY
2352
2353 .PP
2354 Jak již bylo zmíněno, systemtap používá jako výchozí tzv. "kernel runtime
2355 backend", který pracuje na principu jaderného modulu. To přináší výše zmíněná
2356 bezpečnostní úskalí. Systemtap nově obsahuje dva prototypy nových "backendů", které
2357 lze aktivovat volbami \fI\-\-runtime=dyninst\fR a \fI\-\-runtime=bpf\fR.
2358
2359 \fI\-\-runtime=dyninst\fR využívá Dyninst a
2360 lze jej použít k instrumentaci uživatelských procesů. Není založen na bázi jaderných
2361 modulů a nevyžaduje rootovské oprávnění. Zůstávají v něm ale v platnosti omezení
2362 na povolené typy sond.
2363
2364 \fIDyninst\fR backend pracuje v režimu připojení se k cílovému procesu, proto
2365 vyžaduje volbu \fI\-c COMMAND\fR, nebo \fI\-x PID\fR process. Napřiklad:
2366 .SAMPLE
2367 stap \-\-runtime=dyninst \-c "stap \-V" \\
2368 \-e "probe process.function("main")
2369 { println("hi from dyninst!") }"
2370 .ESAMPLE
2371
2372 Pro správnou funkci \fIdyninst\fR runtime může být nezbytné zapnout na cílovém
2373 systému SELinux volbu allow_execstack:
2374 .SAMPLE
2375 # setsebool allow_execstack 1
2376 .ESAMPLE
2377
2378 \fI\-\-runtime=bpf\fR překládá systemtap skript na extended Berkeley Packet
2379 Filter (eBPF) program. Linuxové jádro kontroluje eBPF programy z hlediska
2380 bezpečnosti, a spouští je na svém interním virtuálním stroji. Tento "runtime
2381 backend" je v časné fázi vývoje, a momentálně trpí řadou omezení,
2382 viz \fIstapbpf\fR(8).
2383
2384 .SH NÁVRATOVÝ KÓD
2385
2386 V případě úspěšného běhu vrátí příkaz stap kód 0 (exit code). V opačném
2387 případě se na standardní chybový výstup může vypsat chybová hláška a stap vrátí
2388 nenulový kód. Pro zvýšení upovídanosti použijte
2389 .I \-v
2390 nebo
2391 .I \-vp N .
2392
2393 V "listing" režimu
2394 .RI ( \-l " and " \-L ),
2395 se chyby obvykle potlačují. Pokud byla nalezena alespoň jedna sonda vyhovující
2396 zadaným požadavkům, stap skončí s návratovým kódem 0.
2397
2398 Skript, který skončí svůj běh na žádost uživatele použitím ^C / SIGINT, se
2399 považuje za úspěšně ukončený.
2400
2401 .SH ZASTARÁVÁNÍ
2402 Během vývoje systemtapu dochází občas ve skriptovacím jazyce k nekompatibilním
2403 změnám, takže staré skripty mohou přestat fungovat. V takovém případě může
2404 pomoci volba
2405 .I \-\-compatible VERSION
2406 kde se určí poslední známá verze systemtapu, se kterou daný skript fungoval.
2407
2408 Při použití volby
2409 .I \-\-check\-version
2410 vypíše systemtap varování pokud narazí při lexikální analýze na nekompatibilní
2411 element. Informace o zastarávání se udržují v souboru NEWS.
2412
2413 Smyslem mechanizmu zastarávání je přinést žádoucí inovace skriptovacího jazyka
2414 a současně nerozbít kompatibilitu se starými existujícími skripty. Mechanizmus
2415 zastarávání by tedy měl být chápán především jako
2416 .I služba
2417 přinášející pohodlí uživatelům (a nepohodlí vývojářům) spíše než naopak.
2418
2419 Poznamenejme, že tapset identifikátory s předponou "_" jsou považovány
2420 za interní a občas podstupují změny při kterých je těžké zaručit zpětnou
2421 kompatibilitu i při použití mechanizmu zastarávání. V případě potřeby, prosím,
2422 navrhněte takový symbol k regulernímu zveřejnění.
2423
2424 .SH SOUBORY
2425 .TP
2426 Důležité soubory a jim příslušné cesty dokumentuje manuálová stránka stappaths (7).
2427
2428 .SH VIZ TAKÉ
2429 .nh
2430 .nf
2431 .IR stapprobes (3stap),
2432 .IR function::* (3stap),
2433 .IR probe::* (3stap),
2434 .IR tapset::* (3stap),
2435 .IR stappaths (7),
2436 .IR staprun (8),
2437 .IR stapdyn (8),
2438 .IR systemtap (8),
2439 .IR stapvars (3stap),
2440 .IR stapex (3stap),
2441 .IR stap\-server (8),
2442 .IR stap\-prep (1),
2443 .IR stapref (1),
2444 .IR awk (1),
2445 .IR gdb (1)
2446
2447 .SH CHYBY
2448 Prosím, použijte následující bugzilla link, nebo náš mailing list.
2449 .nh
2450 .BR http://sourceware.org/systemtap/ ", " <[email protected]> .
2451 .hy
2452 .PP
2453 .IR error::reporting (7stap),
2454 .nh
2455 .BR https://sourceware.org/systemtap/wiki/HowToReportBugs
2456 .hy