stap

JMÉNO

stap - překladač a řadič systemtap skriptů

POUŽITÍ

stap [ VOLBY ] JMÉNO_SOUBORU [ ARGUMENTY ] stap [ VOLBY ] - [ ARGUMENTY ] stap [ VOLBY ] -e SKRIPT [ ARGUMENTY ] stap [ VOLBY ] -l PROBE [ ARGUMENTY ] stap [ VOLBY ] -L PROBE [ ARGUMENTY ] stap [ VOLBY ] --dump-probe-types stap [ VOLBY ] --dump-probe-aliases stap [ VOLBY ] --dump-functions

POPIS

Program stap je hlavním uživatelským rozhraním nástroje systemtap. Přijímá požadavky na sondování systému (probing) zapsané v jednoduchém skriptovacím jazyce, překládá je do jazyka C, výsledný kód zkompiluje a vytvoří jaderný modul, který následně zavede do běžícího linuxového jádra nebo dyninst instrumentačního nástroje, aby prováděl požadovanou analýzu zkoumaného systému. Skript může být čten ze souboru (JMÉNO_SOUBORU), ze standardního vstupu (v tom případě použijte "-" namísto JMÉNO_SOUBORU), z příkazové řádky (prostřednictvím přepínače -e SKRIPT, případně -E SKRIPT). Program běží dokud není přerušen uživatelem, nebo dokud skript nezavolá exit(), nebo dokud nedojde k nastřádání dostatečného množství tzv. měkkých chyb (soft errors). Jazyk, který je popsán níže v sekci SKRIPTOVACÍ JAZYK, je striktně typovaný, imperativní, bez explicitních deklarací, procedurální, vhodný k prototypování a inspirovaný awk a C. Umožňuje spojit místo ve zdrojovém kódu linuxového jádra, nebo uživatelské aplikace, případně systémovou událost s obslužnými rutinami, což jsou bloky kódu vykonávané synchronně. Koncepčně to připomíná skriptování v gdb.

PŘEHLED DOKUMENTACE

Pro SystemTap existuje množství vzdělávacích, dokumentačních a referenčních materiálů jak v online podobě, tak i v rámci distribučních balíčků. Online dokumentace se nachází na projektovém webu https://sourceware.org/systemtap/

man stránky
stap (tato stránka)	syntaxe jazyka, koncepty, funkce, volby
stapprobes	sondážní body a jejich kontextové proměnné
stapref	rychlá reference pro syntaxi jazyka
stappaths	seznam důležitých umístění včetně knih a odkazů
stap-prep	instalátor závislostí jako např. ladicích informací jádra
tapset::*	vygenerovaný seznam tapsetů
probe::*	vygenerovaný seznam tapsetových přezdívek
function::*	vygenerovaný seznam tapsetových funkcí
macro::*	vygenerovaný seznam tapsetových maker
stapvars	vybrané globální proměnné definované v tapsetech
staprun, stapdyn, stapbpf	programy pro spuštění zkompilovaných systemtap skriptů
systemtap	systémová služba, analýza startu systému
stap-server	kompilační server
stapex	několik velmi jednoduchých příkladů
knihy
Beginner's Guide	učebnice základů s praktickými ukázkami
Tutorial	hutný úvod, cvičení
Language Reference	podrobný manuál skriptovacího jazyka
Tapset Reference	man stránky tapsetů v podobě knihy
odkazy
example scripts	množství nástrojů pro správu systému, ukázkových skriptů a výukových hraček

VOLBY

Příkaz stap akceptuje následující volby. Jakákoliv jiná volba vypíše seznam podporovaných voleb. Volby lze uvést na příkazové řádce, jak je obvyklé. Pokud existuje $SYSTEMTAP_DIR/rc, mohou být volby načteny odtud a interpretovány nejdříve. Pokud není $SYSTEMTAP_DIR nastavena, použije se $HOME/.systemtap jako výchozí. V některých případech může výchozí hodnota volby záviset na konkrétní konfiguraci systému a proto zde není přímo uvedena. V takovém případě může pomoci "stap --help".

-

Načte skript ze standardního vstupu namísto ze souboru JMÉNO_SOUBORU, pokud ovšem není dáno -e SKRIPT.

-h --help

Zobrazí nápovědu.

-V --version

Zobrazí verzi.

-p NUM

Zastaví po dokončení procesní fáze NUM. Procesní fáze jsou očíslované 1-5 (parse, elaborate, translate, compile, run). Viz sekce ZPRACOVÁNÍ .

-v

Zvýší upovídanost pro všechny procesní fáze. Tuto volbu lze opakovat pro zvýšení množství informativního (?) výstupu.

--vp ABCDE

Zvýší upovídanost pro jednotlivé procesní fáze. Například, "--vp 002" přidá 2 jednotky upovídanosti procesní fázi 3. Kombinace "-v --vp 00004" přidá 1 jednotku upovídanosti všem procesním fázím, a další čtyři jednotky fázi 5.

-k

Zachová dočasný procesní adresář, který se jinak po dokončení skriptu smaže. To může být užitečné, chceme-li zkoumat vygenerovaný C kód, nebo jej znovu použít pro vytvoření jaderného modulu.

-g

Guru režim. Umožní použít potenciálně nebezpečné expertní konstrukce, jako například vložený (embedded) C kód v rámci systemtap skriptu.

-P

Režim prohledávání prologu (prologue-searching). Ekvivalentem je --prologue-searching=always. Aktivuje heuristiku pro obcházení problémů s nekonzistentními ladicími informacemi pro kontextové proměnné parametrů funkcí.

-u

Vypne optimalizace jako např. odstraňování nepotřebného kódu (a mnoho dalších) během 2., či 3. procesní fáze (elaboration, translation).

-w

Potlačí všechny varovné hlášení.

-W

Zachází s varováními stejně jako s chybami.

-b

Tzv. "bulk" režim pro přenos dat z jádra k uživateli. V tomto režimu jsou data pro jednotlivé CPU přenášena odděleně a zapisována do samostatných souborů. Pro jejich případné sloučení lze použít příkaz stap-merge.

-t

Sbírá různé časovací informace jako například počet aktivací (probe hits) pro jednotlivé sondy, průměrný čas strávený v jednotlivých sondách, atd.

-s NUM

Nastaví velikost bufferu pro přenos dat ze systemtap modulu k uživateli na NUM MB. Na víceprocesorovém systému v "bulk" režimu bude mít tuto velikost každý jednotlivý buffer.

-I DIR

Přidá DIR mezi cesty ve kterých se vyhledávají tapset skripty. Více informací obsahuje popis procesní fáze 2.

-D NAME=VALUE

Přidá danou direktivu do Makefile systemtap modulu. Toho lze využít například k předefinování různých omezení popsaných níže.

-B NAME=VALUE

Předá danou direktivu příkazu make při sestavování systemtap modulu. Toho lze využít k přidání nebo změně "kconfig" voleb.

-a ARCH

Použije režim křížového překladu (cross compilation) pro danou cílovou architekturu. Tato volba vyžaduje přístup ke kompilačnímu serveru a obvykle se používá spolu s volbami -B CROSS_COMPILE=arch-tool-prefix- a -r /build/tree.

--modinfo NAME=VALUE

Přidá pár klíč/hodnota ve formě makra MODULE_INFO do vygenerovaného modulu. Toho lze využít k nastavení nebo úpravě různých jaderných kontrol souvisejících s modulem.

-G NAME=VALUE

Nastavuje hodnotu globální proměnné NAME na VALUE při volání programu staprun. Tak lze nastavit hodnotu skalární globální proměnné skriptu.

-R DIR

Prohledává DIR na systemtap runtime zdroje. Výchozí hodnotu DIR lze zobrazit např. prostřednictvím "stap --help".

-r /DIR

Použije daný jaderný "build tree". Lze také nastavit prostřednictvím proměnné prostředí SYSTEMTAP_RELEASE .

-r RELEASE

Určí "release" jádra v rámci "build tree" /lib/modules/RELEASE/build. Lze též nastavit prostřednictvím proměnné prostředí SYSTEMTAP_RELEASE .

-m MODULE

Použije dané jméno pro vygenerovaný jaderný modul namísto obvyklého náhodně vygenerovaného jména. Takto vygenerovaný modul se pak navíc zkopíruje do aktuálního adresáře.

-d MODULE

Přidá do systemtap modulu ladicí informace o symbolech a informace pro odvíjení zásobníku pro daný MODULE. Tak lze umožnit symbolické tracebacky pro MODULE i když do něj není explicitně vložena sonda.

--ldd

Přidá do systemtap modulu ladicí informace pro všechny uživatelské spustitelné soubory nebo DSO knihovny, které ldd podezřívá z užitečnosti pro požadovanou analýzu. Totéž bude do systemtap modulu přidáno i pro moduly vyjmenované pomocí přepínačů -d. Upozornění: --ldd může systemtap modul značně zvětšit.

--all-modules

Ekvivalent pro "-dkernel" a "-d" pro každý z momentálně zavedených modulů. Upozornění: --all-modules může systemtap modul značně zvětšit.

-o FILE

Přesměruje výstup do souboru FILE. V bulk režimu se použije pro každou CPU samostatný soubor s prefixem FILE_ (FILE_cpu s -F) následovaným číslem CPU. Pro FILE je podporován strftime(3) formát.

-c CMD

Zavede a nastartuje systemtap modul, spustí příkaz CMD, a vše ukončí spolu s CMD. Vedlejším efektem je nastavení target() na pid CMD.

-x PID

Nastaví target() na PID. Takto lze psát skripty se zaměřením na daný proces. V tomto případě systemtap skript běží bez ohledu na životní cyklus procesu PID.

-e SKRIPT

Spustí SKRIPT. Příklad: stap -e "probe oneshot { log("hello") }"

-E SKRIPT

Spustí SKRIPT. Ten běží spolu s hlavním skriptem určeným pomocí -e nebo načteným ze souboru. Tuto volbu lze opakovat pro načtení většího počtu skriptů. Taktéž ji lze použít v kombinaci s -l/-L.

-l PROBE

Namísto obvyklého spuštění systemtap skriptu, tato volba vypíše všechny sondy které odpovídají parametru PROBE. PROBE může obsahovat zástupné symboly a přezdívky, ale ne seznam čárkou oddělených sondážních bodů. Pokud PROBE neodpovídá žádné dostupné sondě, bude výsledkem chyba.

-L PROBE

Podobá se "-l", ale navíc vypíše dostupné lokální proměnné.

-F

Bez -o tato volba zavede systemtap modul, spustí sondy a odpojí se od běžícího modulu. V kombinaci s volbou -o spustí staprun na pozadí jako démon a vypíše jeho pid.

-S size[,N]

Nastavuje maximální velikost výstupního souboru a případně také počet výstupních souborů. V případě, že dojde k překročení maximální velikosti výstupního souboru size , přepne systemtap svůj výstup do dalšího souboru. Pakliže počet výstupních souborů překročí N , systemtap odstraní nejstarší výstupní soubor. Druhý z argumentů lze vynechat.

-T TIMEOUT

Ukončit skript po uplynutí TIMEOUT sekund.

--skip-badvars

Ignoruje neidentifikovatelné nebo nedostupné kontextové proměnné a, aniž by došlo k chybě, nahradí jejich hodnotu nulou.

--prologue-searching[=WHEN]

Režim prologue-searching. Aktivuje heuristiku k vyrovnání se s nekvalitními ladicí informacemi pro kontextové proměnné funkčních parametrů. WHEN může být "never" (nikdy), "always" (vždy), nebo "auto" (tj. zapnuto na základě heuristiky). Když WHEN chybí, předpokládá se "always". Bez explicitní specifikace se předpokládá "auto".

--suppress-handler-errors

Zabalí všechny obslužné rutiny do obálky podobné následujícímu kódu:

 

blok, který způsobuje chyby v době běhu, bude tiše potlačen. Potlačené chyby se nebudou vyhodnocovat proti limitu MAXERRORS. V tomto režimu je taktéž potlačeno testování MAXSKIPPED , takže při běhu skriptu může dojít k libovolnému množství chyb. Celkové počty chyb budou nicméně reportovány při ukončení skriptu.

--compatible VERSION

Z uživatelského hlediska se tato volba pokouší napodobit chování systemtapu dané verze a umožnit tak běh starším skriptům. Viz též sekce ZASTARÁVÁNÍ.

--check-version

Tato volba slouží k ověření, zda aktivní skript obsahuje konstrukce závislé na verzi systemtapu. Viz též sekce ZASTARÁVÁNÍ.

--clean-cache

Tato volba smaže zastaralé položky v cache adresáři. To se normálně děje po úspěšném ukončení skriptu, ale tato volba vyčistí cache explicitně, a pak ukončí systemtap. Viz sekce CACHE.

--color[=WHEN], --colour[=WHEN]

Tato volba ovládá obarvování výstupu. WHEN může být "never" (nikdy), "always" (vždy), nebo "auto" (zapnuto pokud jde výstup do terminálu). Pokud WHEN chybí, předpokládá se "auto". Barvy lze měnit prostřednictvím proměnné prostředí SYSTEMTAP_COLORS. Formát je následující: klíč1=hodnota1:klíč2=hodnota2:klíč3=hodnota3 ...atd. Platné klíče jsou: "error", "warning", "source", "caret", a "token". Hodnotami jsou "Select Graphic Rendition" (SGR) parametry. Viz dokumentace k použitému terminálu. Příklad výchozího nastavení je: error=01;31:warning=00;33:source=00;34:caret=01:token=01. Pokud SYSTEMTAP_COLORS chybí, použije se výchozí nastavení. Pokud to je prázdné nebo chybné, obarvování se vypne.

--disable-cache

Tato volba vypne veškeré používání cache. Žádné soubory nebudou do cache adresáře zapsány, ani z něj čteny.

--poison-cache

Tato volba zachází se soubory v cache jako s neplatnými. Žádné soubory nebudou z cache čteny, ale nové soubory budou do cache zapsány na základě aktuálního běhu. Tato volba má pomoci hledat chybu v případě, kdy se cache systemtapu zdá fungovat chybně. Pokud tato volba pomohla, provděpodobně je v někde v systemtapu chyba, o které by vývojáři rádi věděli. Prosím, nahlašte ji.

--privilege[=stapusr | =stapsys | =stapdev]

Tato volba zkontroluje skript na přítomnost konstruktů, které nejsou povoleny pro zadanou úroveň oprávnění (viz NEPRIVILEGOVANÍ UŽIVATELÉ). Pokud skript nepovolené konstrukty obsahuje, kompilace skončí chybou. Pokud je stapusr nebo stapsys specifikováno při použití kompilačního serveru (viz --use-server), pak server zkontroluje skript a, pokud kompilace uspěje, server kryptograficky podepíše výsledný modul, kde specifikuje, že daný modul je bezpečný pro použití uživatelem s danou úrovní oprávnění. Pokud se --privilege nespecifikuje, -pN se také nespecifikuje s N < 5 a daný uživatel není root ani člen skupiny stapdev, pak stap automaticky přidá odpovídající --privilege volbu k již specifikovaným volbám.

--unprivileged

Ekvivalent pro --privilege=stapusr.

--use-server[=HOSTNAME[:PORT] | =IP_ADDRESS[ :PORT] | =CERT_SERIAL]

Specifikuje kompilační server(y) pro kompilaci, a/nebo - v kombinaci s --list-servers a --trust-servers (viz níže) pro výpis serverů. Pokud je tato volba použita bez parametrů v neprivilegovaném režimu (viz --privilege) , pak výchozí server, který bude pro kompilaci použit, bude některý z dostupných kompatibilních serverů "online SSL peer", a zároveň "module signer". Jinak bude jako výchozí server použit některý z dostupných kompatibilních serverů "online SSL peer". --use-server lze použít opakovaně a v tomto případě bude seznam použitelných serverů postupně rozšiřován v daném pořadí. Servery lze specifikovat pomocí hostaname, IP adresy, nebo seriálním číslem certifikátu (získaným prostřednictvím --list-servers). Poslední možnost je nejběžnější pro (od)nastavování důvěryhodnosti serveru. Viz --trust-servers níže. Pokud je server specifikován pomocí hostname nebo IP adresy, pak je volitelně možné určit i číslo portu. To je vhodné pro přístup k serverům, které nejsou na lokální síti, nebo pro specifikování konkrétního serveru. IP adresou může být jak IPv4, tak IPv6. Pokud existuje více než jedno rozhraní s danou link-local IPv6 adresou, pak je možné zvolit konkrétní rozhraní připojením znaku "%" a názvu rozhraní k adrese, například: "fe80::5eff:35ff:fe07:55ca%eth0". Pro určení čísla portu IPv6 adresy je nutné uzavřít adresu do hranatých závorek , aby došlo k oddělení adresy od čísla portu. Například: "[fe80::5eff:35ff:fe07:55ca]:5000" nebo "[fe80::5eff:35ff:fe07:55ca%eth0]:5000". Pokud --use-server nebylo specifikováno, -pN nebylo specifikováno s N < 5, a uživatel není root, není člen skupiny stapdev, ale je členem skupiny stapusr, pak stap automaticky přidá --use-server k již specifikovaným volbám.

--use-server-on-error[=yes|=no]

Požádá stap, aby zkusil kompilaci znovu s použitím kompilačního serveru, pokud lokální kompilace selže. Pokud tato volba není specifikována, pak se za výchozí považuje --use-server-on-error= no --use-server-on-error je ekvivalentem pro --use-server-on-error= yes. Kompilace může být přerušena pro určitý typ chyby, jako například nedostatek dat nebo zdrojů. K tomu může dojít i během rekompilace. Pro rekompilaci budou servery voleny automaticky tak, jako by byla použita volba --use-server bez parametrů.

--list-servers[=SERVERS]

Zobrazí stav požadovaných SERVERS, kde SERVERS je čárkou oddělený seznam atributů popisujících servery. Sjednocení atributů slouží k vygenerování seznamu serverů. Dostupné atributy jsou:

Pokud není dán žádný argument, pak výchozí volbou je specified. Pokud žádné servery nebyly specifikovány pomocí --use-server, pak budou vypsány výchozí servery pro --use-server. Poznamenejme, že --list-servers používá avahi-daemon k detekci online serverů. Pokud tato služba není dostupná, pak --list-servers nebude detekovat žádné online servery. Aby --list-servers detekoval servery poslouchající na IPv6 adresách, musí konfigurační soubor avahi démona, /etc/avahi/avahi-daemon.conf , obsahovat "use-ipv6=yes". Po případné úpravě konfiguračního souboru je třeba službu restartovat.

--trust-servers[=TRUST_SPEC]

Nastavit nebo odvolat natavení důvěryhodnosti kompilačního serveru specifikovaného pomocí --use-server podle TRUST_SPEC, kde TRUST_SPEC je čárkou oddělený seznam typů důvěryhodnosti. Podporované typy jsou:

Pokud žádný argument není nastaven, použije se výchozí hodnota ssl. Pokud pomocí --use-server, nebyly určené žádné servery, žádná relace důvěry nebude nastavena ani zrušena.

Dokud se nespecifikuje no-prompt, uživatel bude požádán o potvrzení požadované akce.

--dump-probe-types

Vypíše všechny podporované typy sond a skončí. Pokud je též nastaveno --privilege=stapusr , pak tento seznam bude omezen tak, aby vidět byly pouze sondy, které má daný uživatel právo použít.

--dump-probe-aliases

Vypíše všechny přezdívky nalezené v tapset skriptech a skončí.

--dump-functions

Vypíše všechny veřejné funkce nalezené v tapset skriptech a skončí. Také vypíše jejich parametry a typy. Návratový typ "unknown" značí, že daná funkce nevrací hodnotu. Poznamenejme, že ne všechny návratové typy / typy parametrů je vždy možné při syntaktické analýze stanovit. Nestanovené typy budou též označeny jako "unknown". Funkce --dump-functions je náročná na paměť a proto nemusí správně fungovat s --use-server pokud na cílovém systému narazí na rlimit pro paměť procesu, například prostřednictvím konfiguračního souboru ~stap-server/.systemtap/rc, viz stap-server(8).

--remote URL

Provede skript na vzdáleném stroji. Tuto volbu je možné opakovat pro provedení skriptu na více strojích. Procesní fáze 1-4 se provedou lokálně, jak je běžné, a pak během fáze 5, se modul zkopíruje na specifikované stroje a na nich provede. Přijatelné URL jsou:

--remote-prefix

Oprefixuje každou řádku výstupu "N: ", kde N je index vzdáleného stroje ze kterého daný výstup pochází.

--download-ladicíinfo[=OPTION]

Podle OPTION zapne, vypne, nebo nastaví timeout pro funkci automatického stahování balíčků s ladicími informacemi, kterou nabízí ABRT. Přípustné hodnoty pro OPTION jsou:

--rlimit-as=NUM

Určí maximální velikost virtuální paměti procesu v bajtech. Bez specifikace NUM nebude žádný limit nastaven.

--rlimit-cpu=NUM

Určí limit pro čas CPU v sekundách. Bez specifikace NUM není žádný limit nastaven.

--rlimit-nproc=NUM

Určí maximální počet procesů které může systemtap vytvořit. Bez specifikace NUM není žádný limit nastaven.

--rlimit-stack=NUM

Nastaví maximální velikost zásobníku v bajtech. Bez specifikace NUM není žádný limit nastaven.

--rlimit-fsize=NUM

Nastaví maximální velikost souboru, který je možno vytvořit, v bajtech. Bez specifikace NUM není žádný limit nastaven.

--sysroot=DIR

Nastaví "sysroot" adresář, kde budou umístěny cílové soubory (programy, knihovny atd.) Po nastavení -r RELEASE bude v adresáři "sysroot" hledán "build" adresář jádra, ovšem po nastavení -r /DIR nebude "sysroot" prohledáván na "build" adresář jádra.

--sysenv=VAR=VALUE

Nastaví alternativní hodnotu proměnné prostředí pokud se tato hodnota na vzdáleném systému liší. Předpokládá se, že proměnné vyjadřující cesty budou uvedeny jako relativní cesty vzhledem k --sysroot (pokud je nastaven).

--suppress-time-limits

Potlačí -DSTP_OVERLOAD*, -DMAXACTION a -DMAXTRYLOCK. Vyžaduje guru režim (-g).

--runtime=MODE

Nastaví runtime režim pro procesní fázi 5. Validní hodnoty jsou kernel (výchozí), dyninst a bpf. Viz sekce ALTERNATIVNÍ RUNTIME.

--dyninst

Zkratka pro --runtime=dyninst.

--save-uprobes

Na strojích, kde si SystemTap musí sestavit svůj vlastní modul "uprobes" (jádra před 3.5), tato volba instruuje SystemTap, aby po sestavení tento pomocný modul zachoval v aktuálním adresáři.

--target-namespaces=PID

Nastavuje cílový "namespace" (jmenný prostor procesů) na "namespace" do kterého patří PID. Volba souvisí s "namespace-aware" tapset funkcemi. Pokud cílový "namespace" není specifikován, použije se "namespace" v kterém běží stap.

--monitor=INTERVAL

Umožňuje zobrazovat informace o stavu modulu (čas běhu, jméno modulu, id uživatele, který modul aktivoval, informace o paměti, globální proměnné, seznam sond včetně jejich statistik). Je možno nastavit volitelný parametr INTERVAL, který určuje obnovovací frekvenci stavového okna v sekundách. Činnost modulu lze ovládat následujícími klávesami:

ARGUMENTY

Všechny další argumenty z příkazové řádky se předají kompilátoru ke zpracování. Viz níže.

SKRIPTOVACÍ JAZYK

Skriptovací jazyk systemtapu připomíná awk a C. Existují v něm dva hlavní konstrukty: sondy a funkce. V jejich rámci se používají příkazy a výrazy se syntaxí podobnou syntaxi jazyka C.

OBECNÁ SYNTAXE

Bílé místo se ignoruje. Podporovány jsou komentáře tří typů: Literály jsou buďto řetězce uzavřené v uvozovkách (dovolují obvyklé C escape sekvence se zpětnými lomítky, které lze řetězit podobně jako v C), nebo celá čísla (dekadická, hexadecimální, nebo oktalová, zapsaná stejně jako v C). Maximální délka řetězce je rozumně omezená na několik set bajtů. Celá čísla jsou 64-bitová se znaménkem. Parser formálně přijímá i kladná čísla nad 2**63, pro které pak používá modulo aritmetiku z důvodu přetečení (wrap around). Na konci příkazové řádky lze skriptům předat parametry. V rámci skriptu k nim pak lze přistupovat prostřednictvím $1 ... $<NN> pokud jde literály neuzavřené do uvozovek, nebo @1 ... @<NN> pokud jde o řetězcové literály uzavřené do uvozovek. Počet argumentů je přístupný prostřednictvím $# (jakožto číslo neuzavřené do uvozovek) nebo prostřednictvím @# (jakožto číslo do uvozovek uzavřené). Tyto symboly lze použit na místě libovolné lexikální jednotky skriptu, a k jejich vyhodnocení dojde již v počáteční fázi překladu (preprocessing).

FÁZE PŘEDZPRACOVÁNÍ (PREPROCESSING)

Součástí lexikální analýzy je jednoduchá fáze předzpracování. V ní lze (ne)vyhodnocovat části kódu na základě podmínky. Příslušná syntaxe se obecně podobá ternárnímu operátoru: podmínka ? výraz1 : výraz2
PODMÍNKA je buďto výraz, jehož formát je určen prvním klíčovým slovem, nebo porovnání řetězcových či numerických literálů, nebo výraz složený z takových podmínek s využitím operátorů || a &&. Nicméně, závorky zde zatím nejsou podporovány, takže je důležité mít na zřeteli, že && má při vyhodnocení přednost před ||. Pokud první částí podmínky je identifikátor kernel_vr nebo kernel_v odkazující se k verzi jádra s příponou ("2.6.13-1.322FC3smp"), nebo bez přípony ("2.6.13"), pak následovat musí jeden z operátorů porovnání: <, <=, ==, !=, >, a >=, a třetí částí podmínky je řetězcový literál vyjadřující verzi jádra v RPM-stylu. Podmínka se považuje za splněnou, pokud verze běžícího jádra (volitelně předefinovaná volbou -r ) se srovnává se zadanou hodnotou. Srovnání provádí glibc funkce strverscmp(). Pokud operátorem je jednoduchá rovnost (==), nebo nerovnost (!=), a pravý operand obsahuje zástupné symboly (* nebo ? nebo [), , pak celý výraz bude interpretován jako "wildcard (mis)match" a bude vyhodnocen glibc funkcí fnmatch(). Pokud první částí podmínky je arch odkazující se k architektuře procesoru (pojmenované podle ARCH/SUBARCH v terminologii jádra), pak druhou částí podmínky je jeden z operátorů: == nebo !=, a třetí částí podmínky je požadovaný řetězcový literál, který může obsahovat zástupné symboly ("wildcard (mis)match"). Podobně, pokud první složkou podmínky je identifikátor jako CONFIG_* odkazující se ke konfigurační volbě jádra, pak druhou částí podmínky je == nebo !=, a třetí částí podmínky je řetězcový literál odpovídající volby (obvykle "y", nebo "m"). Neexistující, nebo nenastavené konfigurační volby v tomto kontextu odpovídají prázdnému řetězci. Vyhodnocení opět probíhá jako "wildcard (mis)match" s využitím fnmatch(). Pokud první částí je identifikátor systemtap_v, pak se test odkazuje k verzi systemtapu, kterou lze volitelně pro staré skripty nastavit prostřednictvím volby --compatible. Operátor porovnání je jako u kernel_v , a pravým operandem je řetězec vyjadřující verzi jádra. Viz též sekce ZASTARÁVÁNÍ níže. Pokud první částí podmínky je systemtap_privilege, pak se test odkazuje k úrovni oprávnění se kterou je systemtap skript překládán. V tomto případě je podmínkou jeden z operátorů == nebo !=, a třetí částí podmínky je jeden z řetězcových literálů "stapusr", "stapsys", nebo "stapdev". Pokud první částí podmínky je identifikátor guru_mode, pak test ověřuje, zda je systemtap skript překládán v "guru" režimu (-g). Operátorem pro tento případ může být == nebo !=, a třetí částí podmínky je číslo. Buďto 1, nebo 0. Pokud prvním indetifikátorem je runtime, testuje se runtime režim (--runtime). Viz sekce ALTERNATIVNÍ RUNTIME níže pro informaci o dostupných runtime backendech. Porovnávací operátor v tomto případě je == nebo !=, a třetí částí podmínky je řetězcový literál odpovídající runtime. Porovnání je typu "wildcard (mis)match" s využitím fnmatch() Poslední možností je situace, kdy PODMÍNKA srovnává prosté číselné, nebo řetězcové literály. VÝRAZ-1 a VÝRAZ-2 představují výskyt nuly nebo více obecných lexikálních jednotek (které mohou obsahovat další vložené podmínky preprocesoru), a jsou preprocesorem předány na vstup parseru v závislosti na vyhodnocení uvedené podmínky. Například následující kód vyvolá kompilační chybu v případě že verze běžícího jádra na cílovém systému je novější, než 2.6.5:
Naproti tomu následující kód umožní elegantně se vyrovnat s různými verzemi jádra:

MAKRA PREPROCESORU

Preprocesor přijímá jednoduchá makra a vyhodnocuje je v rámci samostatné procesní fáze před vyhodnocením podmínek. Makra se definují následující konstrukcí:
Makra (a také parametry uvnitř těla maker) jsou přístupná přidáním prefixu "@" před jejich jméno"
K expanzi maker v současnosti dochází v samostatné preprocesní fázi před zpracováním podmínek. Proto dojde k vyhodnocení všech maker v rámci kondicionálu bez ohledu na konkrétní podmínku. To může vést k nezamýšleným chybám:
První příklad je chybný, protože vyvolá duplicitní definici makra "foo". Za normálních okolností je definice platná lokálně - pouze v souboru kde se vyskytuje. Makro definované v tapset skriptu tedy není veřejně použitelné v rámci uživatelského skriptu. Makra, která mají být veřejně dostupná, lze sdružovat do knihoven s příponou ".stpm" nacházející se v "tapset search path". Tyto soubory mohou obsahovat @define konstrukty, které budou dostupné nejen ve všech tapsetech, ale i v uživatelských skriptech. Volitelně mohou být definice maker v rámci ".stpm" souborů zabaleny v kondicionálech preprocesoru.

KONSTANTY

V rámci tapset skriptů, nebo guru skriptů je možno přistupovat ke konstantním symbolům, jako jsou například makra jazyka C, prostřednictvím vestavěného operátoru @const(). Pokud je potřeba přidat příslušný #include dodatečného hlavičkového souboru, lze tak učinit prostřednictvím vloženého kódu jazyka C.

PROMĚNNÉ

Identifikátory pro proměnné a funkce jsou alfanumerické sekvence, které mohou obsahovat _ a $. Nesmí začínat číslicí (stejně jako v C). Proměnné jsou lokální vzhledem ke svému bloku (funkce nebo sondy) a jejich životnost je spojena s tímto blokem. Skalární proměnné jsou implicitně řetězcového, nebo celočíselného typu. Asociativní pole mohou také obsahovat řetězcové nebo celočíselné hodnoty a jako klíč jim slouží n-tice řetězců nebo celých čísel. Zde je několik příkladů:
Překladač provádí typové odvození (type inference) na všech identifikátorech včetně indexů polí a parametrů funkcí. Nekonzistentní zacházení s typy způsobí chybu překladu. Proměnné lze definovat jako globální, takže mohou být sdíleny mezi sondami a funkcemi, a žijí stejně dlouho jako celé systemtap sezení. Pro globální proměnné existuje jediný jmenný prostor. Přístup ke globálním proměnným je chráněn zámky, viz BEZPEČNOST A OCHRANA SOUKROMÍ. Globální proměnnou lze deklarovat kdekoli ve vnější úrovni zdrojového kódu, tedy mimo bloky sond a funkcí. Globální proměnné, kterým byla přiřazena hodnota, ale nikdy nebyla čtena, budou automaticky zobrazeny na konci systemtap sezení. Překladač se pokusí odvodit datový typ z hodnot a případně, pokud jde o pole, i z klíčů. Volitelně lze globální proměnnou inicializovat řetězcovým, nebo číselným literálem. Zde jsou příklady deklarace globálních proměnných:
Globální proměnné lze také použít jako parametry systemtap modulu. Toho lze dosáhnout buďto použitím přepínače stap -G, nebo modul připravit předem pomocí stap -p4 a parametry mu předat později při jeho zavádění na příkazové řádce programu staprun. Viz staprun(8). Rozsah platnosti globální proměnné lze omezit na tapset soubor, nebo na uživatelský skript prostřednictvím klíčového slova "private". V tom případě je klíčové slovo "global" volitelné. Následující deklarace označuje var1 a var2 jako privátní globální proměnné:
Pole mají omezenou velikost parametrem MAXMAPENTRIES. Viz BEZPEČNOST A OCHRANA SOUKROMÍ Volitelně lze polím (která jsou vždy globální) nastavit maximální velikost v hranatých závorkách, čímž se předefinuje MAXMAPENTRIES pro dané pole. Poznamenejme, že velikost se vztahuje jen k počtu prvků, nikoliv k celkové velikosti pole v paměti. Příklad:
Polím lze nastavit příznak "%". To způsobí, že pokud do pole přidáme více prvků, než pro kolik je dimenzováno, začnou staré prvky mizet (LIFO). To platí jak pro asociativní, tak pro statistická pole, viz níže. Příklad:
Mnohé sondy poskytují kontextové proměnné, což jsou hodnoty získané za běhu z jádra, nebo zkoumané uživatelské aplikace. Jejich identifikátory začínají znakem $. Sekce KONTEXTOVÉ PROMĚNNÉ v manuálové stránce stapprobes(3stap) obsahuje jejich seznamy pro jednotlivé typy sond. Tyto kontextové proměnné se stanou normálními řetězcovými nebo numerickými proměnnými použitelnými ve skriptu, jakmile provedeme příslušné přiřazení (např. foo=$foo). Podívejte se níže na sekci PŘETYPOVÁNÍ, kde je popsáno jak takovou proměnnou přetypovat zpět na ukazatel je-li to třeba.

PŘÍKAZY

Příkazy umožňují procedurální řízení běhu skriptu. Mohou se vyskytovat uvnitř funkcí a obslužných rutin sond. Celkový počet příkazů, které je v reakci na nějakou událost možno spustit, je omezen na hodnotu definovanou makry MAXACTION_* ve vygenerovaném C-kódu a pohybuje se kolem 1000.

EXP

Vyhodnotit řetězcový, nebo číselný výraz a zahodit hodnotu.

{ STMT1 STMT2 ... }

Vykonat každý příkaz v sekvenci v tomto bloku. Poznamenejme, že oddělovače a znaky pro ukončení příkazu nejsou mezi jednotlivými příkazy nezbytné.

;

Prázdný příkaz, nedělat nic. Je užitečný jako volitelný oddělovač mezi příkazy ke zlepšení detekce syntaktických chyb a k upřesnění některých syntaktických nejednoznačností gramatiky.

if (EXP) STMT1 [ else STMT2 ]

Porovnat číselný výraz EXP s nulou. Pak vykonat příkaz STMT1 (EXP není nula), nebo příkaz STMT2 (EXP je nula).

while (EXP) STMT

Dokud má číselný výraz EXP nenulovou hodnotu, spouštěj STMT.

for (EXP1; EXP2; EXP3) STMT

Vykoná EXP1 jako inicializaci. Dokud EXP2 má nenulovou hodnotu, bude vykonávat STMT a iterační výraz EXP3.

foreach (VAR in ARRAY [ limit EXP ]) STMT

Cyklení přes každý prvek globálního pole ARRAY s přiřazením aktuálního prvku proměnné VAR. Pole není v rámci STMT dovoleno měnit. Přidáním operátoru + nebo - za identifikátor VAR nebo ARRAY, se zajistí iterování přes setříděné pole jedním, nebo druhým směrem. Pokud pole obsahuje statistické agregátory, pak přidáním požadovaného operátoru @operator mezi ARRAY a symbol + nebo - určíme třídicí agregační funkci. Viz příklad níže v sekci STATISTIKA. Výchozí je @count. S využitím volitelného klíčového slova limit lze maximální počet iterací omezit na EXP. Poznamenejme, že EXP se vyhodnocuje na začátku smyčky.

foreach ([VAR1, VAR2, ...] in ARRAY [ limit EXP ]) STMT

Podobně jako výše, ovšem v tomto případě je klíčem pole n-tice hodnot. Třídicí příponu lze použít maximálně na jednom z prvků n-tice.

foreach ([VAR1, VAR2, ...] in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT

Podobně jako výše, ovšem iterovat se bude pouze přes prvky, kde klíč vyhovuje dané hodnotě. Pro určení indexu lze použít znak *, se kterým bude zacházeno jako se zástupným symbolem.

foreach (VAR0 = VAR in ARRAY [ limit EXP ]) STMT

Tato varianta foreach uchová aktuální hodnotu při každé iteraci ve VAR0, takže bude odpovídat ARRAY[VAR]. Tohle analogicky funguje s n-ticí klíčů. Třídicí přípony na VAR0 mají stejný význam jako na ARRAY.

foreach (VAR0 = VAR in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT

Podobné jako výše, ovšem iteruje se pouze přes prvky, kde klíče vyhovují daným hodnotám. Pro určení indexu lze použít znak * se kterým bude zacházeno jako se zástupným symbolem.

break, continue

Ukončit, nebo znovu iterovat vnitřní smyčku. Aplikovatelné na while nebo for nebo foreach.

return EXP

Vrátit hodnotu EXP z funkce. Příkaz return není ve funkci povinný. Pokud se vynechá, bude funkce mít speciální návratový datový typ "unknown".

next

Ihned ukončí obslužnou rutinu sondy. To je obzvlášť užitečné u přezdívek, které používají filtrovací podmínky.

try { STMT1 } catch { STMT2 }

Vykonej příkazy v prvním bloku STMT1. Pokud při tom dojde k chybě běhu, ukonči STMT1 a začni provádět STMT2. Případné chyby v STMT2 se budou propagovat do vnějšího catch bloku, pokud tam takový je.

try { STMT1 } catch(VAR) { STMT2 }

Podobně jako v předchozím případě, ale navíc se chybová hláška, jakožto řetězec, uchová v proměnné VAR.

delete ARRAY[INDEX1, INDEX2, ...]

Odstraní z pole prvky určené n-ticí klíčů. Pokud n-tice klíčů obsahuje symbol * na místě indexu, bude s * zacházeno jako jako se zástupným symbolem. Není chybou pokusit se smazat prvek, který neexistuje.

delete ARRAY

Smazat všechny prvky pole ARRAY.

delete SCALAR

Maže hodnotu SCALAR. Celočíselné proměnné budou vynulovány, řetězcové proměnné nastaveny na "", a statistické proměnné budou nastaveny do výchozího prázdného stavu.

VÝRAZY

SystemTap podporuje množství operátorů, které mají syntaxi a sémantiku velmi podobnou jejich C a awk protějškům. Aritmetické operace se provádějí v souladu s pravidly jazyka C pro celá čísla se znaménkem. Dělení nulou nebo přetečení rozsahu se detekuje a způsobí chybu.

binární numerické operátory

* / % + - >> << & ^ | && ||

binární operátory nad řetězci

. (spojení řetězců)

číselné přiřazovací operátory

= *= /= %= += -= >>= <<= &= ^= |=

řetězcové přiřazovací operátory

= .=

unární číselné operátory

+ - ! ~ ++ --

operátory pro srovnávání čísel, řetězců a práci s regulárními výrazy

< > <= >= == != =~ !~

ternární operátor

podmínka ? exp1 : exp2

seskupovací operátor

( exp )

volání funkce

fn ([ arg1, arg2, ... ])

operátor testující členství v poli

exp in array

 

[exp1, exp2, ...] in array

 

[*, *, ... ]in array

REGULÁRNÍ VÝRAZY

Skriptovací jazyk systemtapu podporuje práci s regulárními výrazy. Základní operace testující (ne)shodu řetězce s regulárním výrazem:
První operand musí být výraz vyhodnotitelný na řetězec; druhý operand musí být řetězcový literál obsahující platný regulární výraz. Syntaxe regulárních výrazů podporuje většinu rozšířených regulárních výrazů POSIX standardu. Výjimkou je znovupoužití částí regulárního výrazu ("\1"). Po úspěšném nalezení je text vyhovující regulárnímu výrazu dostupný prostřednictvím tapsetových funkcí matched() a ngroups() následovně:

SONDY

Hlavním syntaktickým konstruktem skriptovacího jazyka jsou sondy (probes). Sondy spojují abstraktní události s bloky příkazů a vytvářejí tak obslužné rutiny událostí. Obecná syntaxe je následující:
Události jsou určeny syntaxí nazývanou sondážní body (probe points). Existuje množství variant sondážních bodů. Některé jsou definovány překladačem a mnohé další jsou definovány v tapset skriptech jako přezdívky. Sondážní body mohou využívat zástupné znaky, být seskupovány, může být určováno jejich pořadí, či mohou být deklarovány jako volitelné. Více podrobností o syntaxi a sémantice sondážních bodů viz stapprobes(3stap). Obslužná rutina sondy se interpretuje relativně ke kontextu dané události. Pro události související s kernel kódem může tento kontext obsahovat proměnné definované ve zdrojovém kódu jádra. Takové "kontextové" proměnné jsou pak přístupné ve skriptu z prefixem "$". Jsou přístupné pouze pokud byly kompilátorem jádra zachovány navzdory optimalizacím. To je stejné omezení s jakým se potýká debugger když pracuje s optimalizovaným kódem. Navíc musí tyto objekty být v momentě vykonávání obslužné rutiny sondy přítomny přímo v nastránkované (in-paged) paměti, protože systemtap nesmí zapříčinit žádné dodatečné stránkování. Některé sondy mají velmi málo kontextových proměnných. Viz stapprobes(3stap). Proby mohou být doplněny podmínkou pro uzamčení, sestávající z jednoduchého booleovského výrazu. Sonda je "odemčená" (tedy neaktivní) vyhodnocuje-li se zamykací podmínka na false. V tomto stavu některé sondy snižují nebo zcela eliminují svoji režii, tedy nekonzumují systémové prostředky. Jakmile se zamykací podmínka vyhodnotí na true bude sonda brzy znovu uzamčena a její obslužná rutina začne brzy být opět volána když nastane příslušná událost. Přestože je zamykání rychlé, trvá nenulový čas, a některé události nemusejí být zachyceny. V případech kdy toto může představovat problém, je lepší zamykání sond nepoužívat. Nové sondážní body lze definovat pomocí přezdívek (probe aliases). Definice přezdívky vypadá podobně jako definice sondy samotné, ale namísto aktivování sondy v daném místě pouze definují nové jméno - přezdívku pro již existující sondážní bod. Existují dva typy přezdívek: "prologue" a "epilogue", které jsou definovány pomocí "=" nebo resp. "+=". Přezdívka typu "prologue" vznikne tak, že se blok příkazů, který následuje definici této přezdívky, přidá před sondu ke které se váže jako její prolog. Naproti tomu přezdíka typu "epilogue" vznikne tak, že blok příkazů, který následuje definici této přezdívky, se přidá za sondu ke které se váže jako její epilog. Například:
definuje nový sondážní bod. syscall.read, který se rozšiřuje na kernel.function("sys_read"), s daným příkazem jako prologem, což je výhodné k předdefinování některých proměnných pro danou přezdívku a/nebo pro přeskočení dané sondy v závislosti na podmínce. Naproti tomu
definuje nový sondážní bod s daným příkazem jako epilogem, což může být užitečné k provedení činností v závislosti na hodnotách proměnných nastavených uživatelem přezdívky. Poznamenejme, že v každém případě jsou příkazy v obslužné rutině přezdívky vykonávány za běhu, takže v danou chvíli zejména nedochází k vyhodnocování/substituci maker. Přezdívku lze použít stejně jako vestavěnou sondu překladače.

FUNKCE

Systemtap skripty mohou definovat funkce. Ty mohou přijímat libovolný počet skalárních (celočíselných nebo řetězcových) parametrů, a vrací jednu skalární funkční hodnotu. Příklad funkce:
Povšimněme si absence explicitních deklarací typů. Typy, jsou odvozeny (inferred) překladačem. Nicméně, pokud je to potřeba, může definice funkce zahrnovat explicitní deklarace návratového typu a/nebo typů argumentů. To je užitečné zejména pro vložené C funkce. V následujícím příkladě je automatické odvození typu nutné jen pro arg2 (řetězec):
Funkce se mohou volat navzájem až do určitého limitu zanoření. Tento limit je definován makrem MAXNESTING ve vygenerovaném zdrojovém kódu modulu a pohybuje se okolo 10. Funkce lze označit za privátní použitím klíčového slova "private". Tím se omezí jejich platnost soubor (tapset nebo uživatelský skript) ve kterém jsou definovány. Příklad:

TISK

Existuje několik funkcí, se kterými překladač zachází neobvykle. Poznamenejme, že data jsou generována v jaderném modulu a před tiskem musí být přenesena do uživatelského prostoru. Tyto funkce formátují hodnoty pro pohodlný tisk do výstupního proudu systemtapu. Varianty funkce sprint* vracejí formátovaný řetězec namísto aby ho přímo vypisovaly.

print, sprint

Výpis jedné nebo více hodnot libovolného typu spojených dohromady.

println, sprintln

vypisují hodnoty stejně jako print a sprint, ale navíc připojují znak nového řádku.

printd, sprintd

Přijímají řetězcový oddělovač a dvě nebo více hodnot libovolného typu, a vytisknou je proložené tímto oddělovačem. Oddělovačem musí být řetězcový literál - konstanta.

printdln, sprintdln

Vytisknou hodnoty proložené oddělovačem podobně jako printd a sprintd, ale zároveň připojí znak konce řádku.

printf, sprintf

přijímají formátovací řetězec s množinou hodnot odpovídajících typů a všechny je vytisknou. Formátovacím řetězcem musí být řetězcový literál - konstanta.

Formátovací řetězec příkazu printf je podobný jako v jazyce C s tím, že zde probíhá typová kontrola. Znak # zapíná alternativní formátování: Oktalovým číslům přidá prefix "0", hexadecimálním "0x", nebo "0X", a netisknutelným znakům v řetězci přidá prefix "escape" sekvence. Příklady:

STATISTIKA

Často je výhodné sbírat statistická data způsobem, který netrpí problémy s exkluzivním zamykáním globálních proměnných, kde se data udržují. Systemtap nabízí řešení ve formě speciálního operátoru pro uchovávání statistických dat a sady agregačních pseudofunkcí. Agregační operátor je <<<, a připomíná přiřazení, nebo operaci pro zápis do výstupního proudu známou z C++. Levý operand je skalární proměnná (nebo /skalární/ prvek pole - viz příklad níže), která musí být deklarována jako globální. Pravým operandem je číselný výraz. Význam je intuitivní: Přidej dané číslo na hromadu nad kterou bude později možno provádět statistické operace. Seznam funkcí pro extrakci statistických údajů je uveden níže. Příklad:
Funkce pro extrakci statistiky jsou neobvyklé. Pro každý výskyt extrakční funkce pracující s daným identifikátorem zajistí překladač výpočet požadovaného statistického údaje. Statistický subsystém tedy funguje "na požádání" a výpočet probíhá v reálném čase na všech dostupných CPU. Zde je seznam extrakčních funkcí. Prvním argumentem každé z nich je ta stejná l-hodnota, která byla použita pro akumulaci statistiky operátorem <<<. Extrakční funkce @count(v), @sum(v), @min(v), @max(v), @avg(v), @variance(v[, b]) počítají počet, sumu, minimum, maximum, aritmetický průměr, a střední kvadratickou odchylku přes všechny nashromážděné hodnoty. Funkčními hodnotami jsou celá čísla. Pole obsahující agregační data lze třídit a/nebo přes ně iterovat. Viz cyklus foreach výše. Střední kvadratická odchylka se vyčísluje s použitím Welfordova algoritmu. Výpočty jsou prováděny v celočíselné aritmetice, proto mohou trpět nízkou přesností. Pro zlepšení přesnosti lze využít volitelný parametr b, tzv. bitový posun, s hodnotami od 0 (výchozí hodnota) do 62. Pro danou statistickou veličinu, resp. jí odpovídající globální proměnnou ve skriptu, lze použít pouze jednu jedinou hodnotu bitového posunu. Vyšší hodnoty bitového posunu zvyšují přesnost, ale zároveň zvyšují riziko přetečení.
K přetečení může dojít zejména při interním násobení velkých čísel. Pokud k tomu dojde, může střední kvadratická odchylka vycházet záporná, což je normálně nepřípustné. Zvažte normalizování vašich dat. Přičtení, či odečtení konstanty ke všem hodnotám statistického vzorku nemění hodnotu střední kvadratické odchylky. Podělení všech hodnot statistického vzorku konstantou způsobí zmenšení střední kvadratické odchylky o čtverec dané konstanty. Dostupné jsou též histogramy. Například @hist_linear(v,start,stop,interval) reprezentuje lineární histogram od "start" do "stop" s inkrementem "interval". Inkrement musí být kladný. Podobně @hist_log(v) představuje binárně logaritmický histogram. Histogram lze vytisknout některou z rodiny print funkcí. Výsledkem je ASCII-art. Příklad:

PŘETYPOVÁNÍ

Jakmile se ukazatel uloží do celočíselné proměnné v rámci systemtap skriptu, překladač ztrácí informaci o typu, která je potřebná k dereferencování.
(viz KONTEXTOVÉ PROMĚNNÉ man stránky stapprobes(3stap)). Použitím operátoru @cast() sdělujeme kompilátoru, jak má interpretovat takové číslo jakožto typovaný ukazatel. Příklad:
Takto bude p interpretován jako ukazatel do struktury/unionu type_name a dereferencovat member . Lze připojit další ->subfield a dereferencovat tak další úrovně. Poznamenejme, že pro přímé dereferencování ukazatele se doporučuje použít funkcí {kernel,user}_{char,int,...}($p). Více v sekci stapfuncs(5). POZNÁMKA: stejný operátor -> se používá jak pro přímý odkaz na člena, tak pro dereferenci ukazatele. Systemtap automaticky interpretuje tuto dvojakost. Volitelná složka module informuje překladač, kde má hledat informaci o daném typu. module lze uvést vícekrát jako seznam s oddělovačem :. Pokud module není explicitně určen, budou pro jeho určení využity ladicí informace, nebo bude nastaven na "kernel" pro funkce a všechny ostatní typy sond. Překladač může vytvořit svůj vlastní modul s informacemi o typech odvozením z hlavičkových souborů uzavřených ve špičatých závorkách v případě, že ladicí informace nejsou k dispozici. Hlavičkovým souborům jádra je třeba přidat řetězec "kernel" jako předponu. Ostatní hlavičkové soubory budou zpracovány s výchozími volbami kompilátoru. Lze specifikovat více hlavičkových souborů za sebou pro vyřešení závislostí.
Hodnoty získané operátorem @cast lze přehledně vytisknout (pretty-print) připojením operátoru $ a $$ jak je popsáno v sekci KONTEXTOVÉ PROMĚNNÉ man stránky stapprobes(3stap). V guru režimu (-g) umožňuje překladač také přiřadit novou hodnotu dereferencovaným ukazatelům. Přetypování je také užitečné v případě void* členů jejichž typ lze určit až za běhu. Příklad:

EMBEDDED C

V guru režimu přijímá překladač vložený C kód v uživatelských skriptech. Takový kód je uzavřen mezi značkami %{ a %} a je doslovně, bez analýzy, vložen do vnější úrovně vygenerovaného kódu systemtap modulu. Protože je vložen do vnější úrovně, je možné takto definovat #include direktivy a různé pomocné definice použitelné ve zbytku kódu. Dalším místem, kde je vložené C povoleno, je tělo funkce. V tomto případě bude tělo systemtap funkce doslovně tvořeno vloženým C kódem uzavřeným mezi značky %{ a %}. Takto vložený C kód může vykonávat libovolnou rozumnou a bezpečnou činnost. Existuje množství nedokumentovaných a komplexních omezení ohledně atomicity, souběžnosti, spotřeby zdrojů a časových omezení, takže jde o pokročilou techniku. Paměťová umístění vyhrazená pro vstupní a výstupní hodnoty jsou zpřístupněna pomocí maker STAP_ARG_* a STAP_RETVALUE. Chyby lze signalizovat pomocí STAP_ERROR, výstup pomocí STAP_PRINTF a návratovou hodnotu lze předat prostřednictvím STAP_RETURN. Zde je několik příkladů:
Typy funkčních hodnot a typ návratové hodnoty odvodí překladač ze způsobu volání dané funkce. Před vytvářením vlastních vložených C funkcí je vhodné prostudovat zdrojový kód, který překladač generuje pro běžné funkce skriptovacího jazyka a tím se inspirovat. Poslední místo, kde je vložené C povoleno, je r-hodnota ve výrazu. V tomto případě se C-kód uzavře mezi značky %{ a %} a interpretuje se jako běžná hodnota výrazu. Předpokládá se pak, že jde o 64 bitové číslo se znaménkem, ovšem pokud se použije značka /* string */, bude hodnota výrazu interpretována jako řetězec. Příklad:
K nastavení bezpečnosti a optimalizace lze použít následující značky:

/* pure */

znamená, že C kód nemá žádné vedlejší efekty a může být v rámci optimalizace zcela zahozen pokud nemá vazby na zbytek kódu.

/* stable */

znamená, že C kód má vždy stejnou hodnotu (při vyvolání v rámci libovolné obslužné rutiny sondy), takže opakovaná volání mohou být nahrazena zapamatovanou hodnotou. Takové funkce nesmí přijímat parametry a musí být /*pure*/.

/* unprivileged */

znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní uživatelé.

/* myproc-unprivileged */

znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní uživatelé, ovšem jen při analýze svých vlastních uživatelských procesů.

/* guru */

znamená, že C kód je tak nebezpečný, že vyžaduje použití guru režimu -g.

/* unmangled */

ve vložené C funkci zpřístupní zastaralou (pre-1.8) syntaxi pro přístup k funkčním parametrům. V tomto případě lze uvnitř funkce kromě STAP_ARG_foo a STAP_RETVALUE použít také THIS->foo a THIS->__retvalue .

/* unmodified-fnargs */

ve vložené C funkci znamená, že parametry nejsou uvnitř těla funkce měněny.

/* string */

ve vložené C funkci znamená, že výraz má typ const char * a mělo by s ním být nakládáno jako s řetězcovou hodnotou namísto numerické (což je výchozí chování).

BUILT-INS

Skripty instalované v umístění definovaném ve stappaths(7) poskytují množství vestavěných sondážních bodů. Ty jsou popsány v man stránce stapprobes(3stap).

ZPRACOVÁNÍ SKRIPTU

Systemtap zpracovává skript v pěti procesních fázích: "parse", "elaborate", "translate", "compile" a "run". Překladač zahájí fázi 1 lexikální analýzou uživatelského skriptu spolu se všemi tapset skripty (což jsou soubory s příponou *.stp) nalezenými v tapset adresáři. Adresáře vyjmenované prostřednictvím -I jsou následně zpracovány také, a to v guru režimu. Adresářová struktura se prohledává do hloubky. Některé podadresáře jsou specifické pro verzi jádra (volba -R ), a podle ní jsou (nebo nejsou) prohledávány, takže skripty specifičtější pro danou verzi jádra mohou předefinovat své méně specifické protějšky. Například pro verzi jádra 2.6.12-23.FC3 by byly prohledávány následující adresáře: 2.6.12-23.FC3/*.stp, 2.6.12/*.stp, 2.6/*.stp, a nakonec *.stp v tomto pořadí. Pokud překlad skončí na konci fáze 1 (-p1), pak překladač na standardní výstup vypíše derivační strom (parse tree). Ve fázi 2 překladač analyzuje vstupní skript, aby vyhodnotil symboly a datové typy. Odkazy na proměnné, funkce a přezdívky, které se nepodaří vyhodnotit lokálně, se vyhodnotí proti tapset skriptům. Pokud je určitý symbol nalezen v tapset skriptu, pak daný tapset bude celý přidán do fronty pro zpracování překladačem. Tento iterativní proces skončí jakmile jsou vyhodnoceny všechny symboly s využitím dané podmnožiny tapset skriptů. Dále se ověří validnost sondážních bodů. Sondy, které se odkazují k umístěním ve zdrojovém kódu ("synchronní sondážní body") vyžadují, aby byly nainstalovány příslušné ladicí informace. V obslužných rutinách sond se naleznou cílové proměnné (ty, které začínají znakem "$") a dekódují se jejich "run-time" lokace. Dále se všechny sondy a funkce optimalizují. Cílem je odstranit zbytečné proměnné, výrazy a funkce, které nemají vedlejší účinky. U vložených C funkcí se předpokládá, že mají vedlejší účinky pokud ovšem neobsahují kouzelnou značku /* pure */. Vzhledem k tomu, že optimalizace mohou způsobit latentní chyby jako je například typová nekompatibilita, nebo neplatné kontextové proměnné, může být v některých případech užitečné optimalizace vypnout přepínačem -u. Nakonec se z kontextu odvodí datové typy proměnných, funkcí, parametrů, polí a indexů. Ukončení překladu po fázi 2 (-p2) způsobí vypsání seznamu všech sond, funkcí a proměnných spolu s jejich odvozenými typy. Nekonzistentní nebo neodvoditelné typy způsobí chybu překladu. Ve fázi 3 překladač zapíše vygenerovaný C kód a vytvoří Makefile který slouží k jeho přeložení do podoby jaderného modulu. Tyto soubory budou umístěny v dočasném adresáři. Zastavení překladače v této fázi (-p3) způsobí vypsání C souboru na standardní výstup. Ve fázi 4 překladač vyvolá jaderný "build systém", aby sestavil systemtap modul. Při tom se v daném dočasném adresáři volá příkaz make. K úspěšnému provedení tohoto kroku je třeba, aby byl nainstalován "build systém" jádra, tj. hlavičkové soubory, config a Makefile soubory a to v obvyklém umístění /lib/modules/VERSION/build. Zastavení překladače v této fázi (-p4) může být užitečné, pokud chceme modul archivovat. Je to také poslední šance zastavit systemtap před zavedením a spuštěním modulu. Ve fázi 5 překladač zavolá pomocný program staprun a předá mu vzniklý systemtap modul. Program staprun zavede modul do jádra, spustí jej a zajišťuje komunikaci s ním dokud činnost modulu neskončí. Jakákoliv chyba běhu, která se vyskytne v obslužných rutinách sond, jako např. vyčerpání dostupné paměti, dělení nulou, příliš hluboké zanoření, nebo překročení "run-time" limitů, způsobí měkkou chybu (soft error). Pokud počet měkkých chyb překročí MAXERRORS, zastaví se všechny sondy (kromě těch, které obsluhují chyby), a zastaví se sezení. Nakonec staprun odstraní modul z jádra a provede úklid.

NEOBVYKLÉ UKONČENÍ

Je dobré neukončovat stap proces násilím, například prostřednictvím signálu SIGKILL, protože proces stapio (potomek procesu stap) a systemtap modul by se nemusely korektně ukončit. Pokud se to přecejen stane, pošlete všem zbývajícím stapio procesům SIGTERM nebo SIGINT a použijte rmmod pro odstranění systemtap modulu z jádra.

PŘÍKLADY

Viz stapex(3stap) , kde se nachází několik krátkých příkladů, nebo viz adresář "examples" v RPM balíčcích "systemtap-client", či "systemtap-testsuite", kde se nachází rozsáhlá sbírka příkladů. Viz stappaths(7stap) pro podrobný popis konkrétních umístění. Příklady jsou také zveřejněny na webové stránce projektu systemtap.

CACHE

Překladač systemtapu ukládá do cache výstup fáze 3 (tj. vygenerovaný C kód) a výstup fáze 4 (tj. zkompilovaný jaderný modul) pokud tyto fáze skončí bez chyb. Obsah cache se použije pokud se znovu překládá stejný skript a za předpokladu, že platí stejné podmínky (verze jádra, verze systemtapu atp.). Cache se nachází v adresáři $SYSTEMTAP_DIR/cache . Velikost cache lze omezit umístěním souboru cache_mb_limit do cache adresáře, přičemž tento soubor obsahuje ASCII číselnou hodnotu limitu, která vyjadřuje velikost cache v MiB. Pokud tento soubor neexistuje, vytvoří se nový s výchozí hodnotou 256. Jde o měkký limit v tom smyslu, že cache bude promazána až po určité době. Dočasně tedy může velikost cache překročit stanovený limit. Zmíněnou periodu je možno nastavit prostřednictvím souboru cache_clean_interval_s umístěného opět v cache adresáři. Předpokládá se, že tento soubor obsahuje ASCII celé číslo vyjadřující časový interval pro promazávání cache v sekundách. Pokud tento soubor neexistuje, vytvoří se nový s výchozí hodnotou 300.

BEZPEČNOST A OCHRANA SOUKROMÍ

Systemtap může být použit jako mocný administrativní nástroj. Může zpřístupnit privátní uživatelské informace v rámci interních jaderných struktur. To se netýká dyninst runtime, viz ALTERNATIVNÍ RUNTIME . Překladač zajišťuje dodržování mnoha různých bezpečnostních omezení během kompilace a běhu modulu. Snaží se zajistit, aby žádná sonda neběžela příliš dlouho, aby nealokovala příliš mnoho paměti, neprováděla nebezpečné operace, nebo nežádoucím způsobem neovlivňovala systém. Při práci s globálními proměnnými se využívají zámky pro čtení a zápis, aby nedocházelo k chybám při souběhu. Pravidelně dochází k testu na deadlocky. Pro zjištění nepřiměřeného použití zámků lze použít přepínač -t. Experimentování se skripty je tedy v zásadě bezpečné. Guru"režim -g umožňuje administrátorům obejít většinu bezpečnostních opatření a umožnit tak invazivní zásahy a změny stavu systému, použít vložené C a obecně zvýšit riziko průšvihu. Za normálních okolností je pro všechny moduly aktivní ochrana proti přetížení. Tu lze vypnout přepínačem --suppress-time-limits. Chyby zachycené při běhu za normálních okolností vedou k čistému ukončení skriptu s chybovou hláškou. Přepínač --suppress-handler-errors umožňuje zcela ignorovat měkké chyby, takže ani po nastřádání jejich většího počtu nedojde k ukončení skriptu.

OPRÁVNĚNÍ

Aby bylo možné spustit systemtap modul v rámci výchozí kernel runtime, musí uživatel splnit jednu z následujících podmínek:

•

být root.

•

být členem skupin stapdev a stapusr

•

být členem skupin stapsys a stapusr ; nebo

•

být členem skupiny stapusr .

Uživatel root, nebo uživatel, který je členem skupin stapdev a stapusr , může přeložit a spustit libovolný systemtap skript. Uživatel, který je členem skupin stapsys a stapusr, může použít předem připravené systemtap moduly za následujících podmínek:

•

Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap kompilačním serverem, který podepsal modul klientovi, který použil volbu --privilege. Viz stap-server(8).

•

Modul byl sestaven s použitím jedné z voleb --privilege=stapsys nebo --privilege=stapusr.

Členové pouze skupiny stapusr mohou používat jen předem připravené moduly za následujících podmínek:

•

Modul je umístěn v adresáři /lib/modules/VERSION/systemtap. Tento adresář musí být vlastněn uživatelem root a nesmí být otevřený pro zápis všem.

nebo

•

Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap kompilačním serverem, který podepsal modul klientovi, který použil volbu --privilege. Podrobnější informace viz stap-server(8).

•

Modul byl přeložen s volbou --privilege=stapusr.

Jaderné moduly vygenerované programem stap se zavádějí do jádra a spouštějí pomocí programu staprun. Staprun je součástí systemtap balíčku určeného k zavádění a odstraňování modulů (za daných podmínek). Slouží také k přenosu dat mezi systemtap modulem a uživatelelm. Protože staprun neprovádí žádné bezpečnostní kontroly modulu se kterým pracuje, bylo by od administrátora systému nemoudré přidat nedůvěryhodného uživatele do skupiny stapdev nebo stapusr .

SECUREBOOT

Pokud má systém v rámci UEFI firmware zapnutý SecureBoot, všechny jaderné moduly musejí být kryptograficky podepsány. (Některá jádra dovolují vypnout SecureBoot za běhu kombinací kláves SysRq-X. Poté nemusí být moduly podepsané.) Kompilační server systemtapu může podepisovat moduly klíčem MOK (Machine Owner Key) který sdílí s daným systémem. Pro více informací viz následující wiki:

LIMITY NA ZDROJE

Mnoho omezení pro využívání prostředků systému se nachází ve formě maker ve vygenerovaném C kódu systemtap modulu. Ty lze předefinovat prostřednictvím přepínače -D. Seznam zmíněných maker:

MAXNESTING

Maximální počet zanořených funkčních volání. Výchozí hodnota se určuje při analýze skriptu. Skripty založené na rekurzi obdrží 10 bonusových slotů.

MAXSTRINGLEN

Maximální délka řetězce. Výchozí hodnota je 128 znaků.

MAXTRYLOCK

Maximální počet iterací při čekání na uvolnění zámku na globální proměnné před tím, než se vyhlásí deadlock a sonda se přeskočí. Výchozí hodnota je 1000 iterací.

MAXACTION

Maximální počet příkazů, které mohou být vykonány během jednoho hitu sondy (s vypnutými přerušeními). Výchozí hodnota je 1000.

MAXACTION_INTERRUPTIBLE

Maximální počet příkazů, které mohou být vykonány během jedné aktivace (probe hit) sondy, která se provádí s povolenými přerušeními. (jako např. sondy begin a end). Výchozí hodnota je 10 * MAXACTION.

MAXBACKTRACE

Maximální počet zásobníkových rámců, které budou zpracovány při výpisu backtrace. Relevantní tapset je [u]context-unwind.stp, a výchozí hodnota je 20.

MAXMAPENTRIES

Maximální počet řádků v každém jednom globálním poli. Výchozí hodnota je 2048. Jednotlivá pole mohou být deklarována s odlišným limitem. Příklad:

 

nebo je možno využít modifikátoru % , čímž se zapne array-wrapping (nahrazování "starých" prvků) jako v následujícím příkladu:
Viz sekce o polích.

MAXERRORS

Maximální množství měkkých chyb, které ještě nezpůsobí ukončení skriptu. Výchozí hodnotou je 0, tedy skript skončí při první měkké chybě. Poznamenejme, že --suppress-handler-errors tento limit vypíná.

MAXSKIPPED

Maximální počet přeskočených sond, který ještě nevede k ukončení skriptu. Výchozí hodnotou je 100. Pozn., že systemtap lze spustit s přepínačem -t (timing), který zobrazí podrobnosti ohledně počtu přeskočených sond. Při použití -DINTERRUPTIBLE=1 se nebudou brát v potaz sondy přeskočené kvůli re-entranci. Dále poznamenejme, že --suppress-handler-errors vypíná i tento limit.

MINSTACKSPACE

Minimální množství volného místa na zásobníku jádra dostatečné pro start sondy. Výchozí hodnota 1024 bajtů. Tato hodnota by měla být dostačující pro vlastní potřebu obslužné rutiny včetně malé rezervy.

MAXUPROBES

Maximální množství současně zamčených uživatelských sond (uprobes). Výchozí hodnota je o něco málo vyšší, než počet uživatelských sond ve skriptu. Tato hodnota musí být relativně velká, protože jednotlivé uživatelské sondy (každá z nich okupuje přibližně 46 bajtů), se alokují pro každý proces a pro každou odpovídající sondu ve skriptu.

STP_MAXMEMORY

Maximální velikost paměti (v kilobajtech), kterou je systemtap modul oprávněn použít. Výchozí hodnota je neomezená. Limit zahrnuje velikost modulu samotného plus dodatečné alokace. Zahrnuty jsou jen přímé alokace provedené systemtap runtime. Nepřímé alokace, které provádějí např, "kprobes", "uprobes", atd., nejsou započteny.

STP_OVEROAD_THRESHOLD, STP_OVERLOAD_INTERVAL

Maximální počet cyklů, které lze strávit v sondách za daný čas (též vyjádřený v cyklech). Při překročení této podmínky dojde k přetížení a skript se zastaví. Výchozí hodnoty jsou 5e+8 a 1e+9, což odpovídá max. 50% povolenému vytížení.

STP_PROCFS_BUFSIZE

Velikost procfs bufferů pro čtení (v bajtech). Výchozí hodnota je MAXSTRINGLEN. Tento limit lze nastavit specificky pro jednotlivé sondy pomocí syntaxe .maxsize(MAXSIZE) .

Pokud skript obsahuje sondy vázané na přerušení, je možné, že k přerušení dojde tak často, že handler daného přerušení ještě nedoběhne zatímco dojde k dalšímu přerušení. V tomto případě bude obslužná rutina přeskočena, aby se zamezilo reentranci. Tento problém lze obejít použitím -DINTERRUPTIBLE=0kodstíněníběžícíobslužnérutinyoddanéhopřerušení. Tento přístup přináší jistou režii, ale v běžných případech zamezí reentranci. Nicméně, sondy v NMI handlerech a v samotném procesu stap, mohou stále být přeskočeny, aby se zamezilo reentranci. Vznikne-li problém při běhu programu stap nebo staprun když už sondy běží, je možné bezpečně zabít oba tyto uživatelské procesy a odstranit systemtap modul pomocí rmmod. Část výstupu se tak nicméně může ztratit.

NEPRIVILEGOVANÍ UŽIVATELÉ

Systemtap umožňuje přístup k interním datům jádra a tedy potenciálně k soukromým datům uživatele. Z tohoto důvodu je plný přístup k systemtapu omezen na uživatele root a na uživatele, kteří jsou členy skupin stapdev a stapusr. Nicméne omezená sada funkcí systemtapu může být dostupná důvěryhodným neprivilegovaným uživatelům. Tito uživatelé jsou členy pouze skupiny stapusr plus případně skupiny stapsys. Tito uživatelé mohou zavést do jádra předem připravený modul, který byl podepsán důvěryhodným kompilačním serverem. Viz popis voleb --privilege a --use-server. Viz také README.unprivileged mezi zdrojovými soubory systemtapu. Tam je mj. popsáno jak nastavit důvěryhodný kompilační server. Omezení která plynou z volby --privilege=stapsys mají zabránit neprivilegovaným uživatelům v Omezení, která plynou z volby --privilege=stapusr mají zabránit neprivilegovaným uživatelům v

OMEZENÍ NA SONDY

Člen skupin stapusr a stapsys má přístup ke všem sondám. Člen pouze skupiny stapusr může použít následující sondy:

OMEZENÍ SKRIPTOVACÍHO JAZYKA

Následující vlastnosti skriptovacího jazyka jsou pro neprivilegovaného uživatele nedostupné:

RUNTIME OMEZENÍ

Neprivilegovaných uživatelů se týkají také následující omezení runtime: Na členy pouze skupiny stapusr se vztahují dodatečná omezení:

OMEZENÍ NA VOLBY PŘÍKAZOVÉ ŘÁDKY

Některé volby příkazové řádky poskytují přístup k funkcionalitě, která nesmí být přístupná žádnému neprivilegovanému uživateli. Konkrétně

OMEZENÍ NA PROMĚNNÉ PROSTŘEDÍ

Neprivilegovaní uživatelé nesmějí nastavit následující proměnné prostředí:

OMEZENÍ NA TAPSETY

Obecně jsou tapset funkce přístupné členům skupiny stapusr pokud nepřistupují k informacím, které by neměl právo získat libovolný uživatelský program běžící s identitou daného uživatele. Existují dvě skupiny tapset funkcí pro neprivilegované uživatele. První kategorie sestává z funkcí, které mohou použít všichni uživatelé, jako napřiklad:
Druhou skupinou jsou tzv. myproc-unprivileged funkce, které mohou sbírat informace pouze o procesech, které daný uživatel vlastní. Skripty, které mají používat myproc-unprivileged funkce musí testovat is_myproc() a volat takové funkce jen když výsledek je 1. Skript se ihned ukončí, pokud tato podmínka nebude splněna. Přiklady myproc-unprivileged funkcí:
Pokud se uživatel patřící pouze do skupiny stapusr pokusí použít tapset funkci, která nespadá do žádné ze zmíněných dvou kategorií, dojde k chybě při kompilaci.

ALTERNATIVNÍ RUNTIME BACKENDY

Jak již bylo zmíněno, systemtap používá jako výchozí tzv. "kernel runtime backend", který pracuje na principu jaderného modulu. To přináší výše zmíněná bezpečnostní úskalí. Systemtap nově obsahuje dva prototypy nových "backendů", které lze aktivovat volbami --runtime=dyninst a --runtime=bpf. --runtime=dyninst využívá Dyninst a lze jej použít k instrumentaci uživatelských procesů. Není založen na bázi jaderných modulů a nevyžaduje rootovské oprávnění. Zůstávají v něm ale v platnosti omezení na povolené typy sond. Dyninst backend pracuje v režimu připojení se k cílovému procesu, proto vyžaduje volbu -c COMMAND, nebo -x PID process. Napřiklad:
Pro správnou funkci dyninst runtime může být nezbytné zapnout na cílovém systému SELinux volbu allow_execstack:
--runtime=bpf překládá systemtap skript na extended Berkeley Packet Filter (eBPF) program. Linuxové jádro kontroluje eBPF programy z hlediska bezpečnosti, a spouští je na svém interním virtuálním stroji. Tento "runtime backend" je v časné fázi vývoje, a momentálně trpí řadou omezení, viz stapbpf(8).

NÁVRATOVÝ KÓD

V případě úspěšného běhu vrátí příkaz stap kód 0 (exit code). V opačném případě se na standardní chybový výstup může vypsat chybová hláška a stap vrátí nenulový kód. Pro zvýšení upovídanosti použijte -v nebo -vp N . V "listing" režimu (-l and -L), se chyby obvykle potlačují. Pokud byla nalezena alespoň jedna sonda vyhovující zadaným požadavkům, stap skončí s návratovým kódem 0. Skript, který skončí svůj běh na žádost uživatele použitím ^C / SIGINT, se považuje za úspěšně ukončený.

ZASTARÁVÁNÍ

Během vývoje systemtapu dochází občas ve skriptovacím jazyce k nekompatibilním změnám, takže staré skripty mohou přestat fungovat. V takovém případě může pomoci volba --compatible VERSION kde se určí poslední známá verze systemtapu, se kterou daný skript fungoval. Při použití volby --check-version vypíše systemtap varování pokud narazí při lexikální analýze na nekompatibilní element. Informace o zastarávání se udržují v souboru NEWS. Smyslem mechanizmu zastarávání je přinést žádoucí inovace skriptovacího jazyka a současně nerozbít kompatibilitu se starými existujícími skripty. Mechanizmus zastarávání by tedy měl být chápán především jako služba přinášející pohodlí uživatelům (a nepohodlí vývojářům) spíše než naopak. Poznamenejme, že tapset identifikátory s předponou "_" jsou považovány za interní a občas podstupují změny při kterých je těžké zaručit zpětnou kompatibilitu i při použití mechanizmu zastarávání. V případě potřeby, prosím, navrhněte takový symbol k regulernímu zveřejnění.

SOUBORY

Důležité soubory a jim příslušné cesty dokumentuje manuálová stránka stappaths (7).

VIZ TAKÉ

stapprobes(3stap),
function::*(3stap),
probe::*(3stap),
tapset::*(3stap),
stappaths(7),
staprun(8),
stapdyn(8),
systemtap(8),
stapvars(3stap),
stapex(3stap),
stap-server(8),
stap-prep(1),
stapref(1),
awk(1),
gdb(1)

CHYBY

Prosím, použijte následující bugzilla link, nebo náš mailing list. http://sourceware.org/systemtap/, <[email protected]>. error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs