.\" {PTM/PB/0.1/18-05-1999/"led wywoania systemowe i sygnay"}
.\" Translation 1999 Przemek Borys <pborys@dione.ids.pl>
.\" Copyright (c) 1991, 1992 Paul Kranenburg <pk@cs.few.eur.nl>
.\" Copyright (c) 1993 Branko Lankester <branko@hacktic.nl>
.\" Copyright (c) 1993, 1994, 1995, 1996 Rick Sladkey <jrs@world.std.com>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	$Id: strace.1,v 1.9 2001/06/12 11:09:04 robert Exp $
.\"
.de CW
.sp
.nf
.ft CW
..
.de CE
.ft
.fi
.sp
..
.TH STRACE 1 "96/02/13"
.SH NAZWA
strace \- led wywoania systemowe i sygnay
.SH SKADNIA
.B strace
[
.B \-dffhiqrtttTvxx
]
[
.BI \-a kolumna
]
[
.BI \-e wyra
]
\&...
[
.BI \-o plik
]
[
.BI \-p pid
]
\&...
[
.BI \-s rozmiarnapisu
]
[
.BI \-u uytkownik
]
[
.I komenda
[
.I arg
\&...
]
]
.sp
.B strace
.B \-c
[
.BI \-e wyra
]
\&...
[
.BI \-O wydatki
]
[
.BI \-S sortuj
]
[
.I komenda
[
.I arg
\&...
]
]
.SH OPIS
.IX "strace komenda" "" "\fLstrace\fR komenda"
.LP
W najprostszym przypadku, 
.B strace
wykonuje zadan komend 
.RI "`" komenda "'"
a si ona nie skoczy.
Strace przechwytuje i nagrywa wywoania systemowe, dokonane przez proces,
oraz sygnay, ktre do niego dotary. Nazwa kadego wywoania, oraz jego
argumenty, s wypisywane na wyjcie standardowe bdu, lub do pliku podanego
w opcji
.BR \-o . 
.LP
.B strace
jest uytecznym narzdziem diagnostyki, debuggowania. Administratorzy
systemw, diagnostycy i napotykacze problemw zauwa, e jest nieocenione
dla rozwizywania problemw z programami, ktrych rde nie ma wprost
dostpnych. Strace bowiem nie potrzebuje rekompilacji aby go uy.
Studenci, hackerzy i oglnie zainteresowani zauwa, e z ledzenia wywoa
systemowych mona si wiele nauczy o systemie. Programici zauwa, e
skoro wywoania systemowe i sygnay s zdarzeniami zachodzcymi na
interfejsie uytkownik/jdro, to ich bliska obserwacja moe by bardzo
uyteczna do izolowania bdw, sprawdzania czystoci i prbowania
wyapywania ulotnych warunkw.
.LP
Kada ledzona linia zawiera nazw wywoania systemowego, za ktr nastpuj
jego argumenty, otoczone nawiasami, oraz jego warto zwracana.
Przykadowe ledzenie komendy ``cat /dev/null'' daje:
.CW
open("/dev/null", O_RDONLY) = 3
.CE
Do bdw (zwykle wartoci zwracane \-1) dopisywany jest symbol errno i
napis bdu.
.CW
open("/foo/bar", O_RDONLY) = -1 ENOENT (No such file or directory)
.CE
Sygnay s drukowane jako symbol, oraz napis sygnau. Fragment ledzenia i
przerwania komendy ``sleep 666'' to:
.CW
sigsuspend([] <unfinished ...>
--- SIGINT (Interrupt) ---
+++ killed by SIGINT +++
.CE
Argumenty s namitnie drukowane w formie symbolicznej.
Przykad ten pokazuje dokonanie przekierowania ``>>xyzzy'':
.CW
open("xyzzy", O_WRONLY|O_APPEND|O_CREAT, 0666) = 3
.CE
Tutaj, wymienione trzy argumenty z open s zdekodowane poprzez rozbicie
argumentu flagi na jego bitowe skadniki i wydrukowanie ich tradycyjnych
nazw, oraz wartoci semkowej praw. Cho tradycyjne, lub natywne uywanie
rni si od ANSI lub POSIX, to te ostatnie formy s jednak preferowane.
W niektrych wypadkach, wyjcie strace moe by bardziej czytelne ni
rda.
.LP
Wskaniki struktury s dereferencjonowane, a czonkowie s odpowiednio
wywietlani. We wszystkich wypadkach argumenty s formatowane w stylu C.
Na przykad, istota komendy ``ls -l /dev/null'' jest przechwytywana jako:
.CW
lstat("/dev/null", {st_mode=S_IFCHR|0666, st_rdev=makedev(1, 3), ...}) = 0
.CE
Zauwa, jak zdereferencjonowano argument `struct stat' i jak wywietlono
kadego czonka. Praktycznie, zauwa jak ostronie zosta zdekodowany
czonek st_mode na jego mask bitow. Zauwa te, e w tym przykadzie,
pierwszym argumentem lstat jest wejcie wywoania systemowego, a drugim jego
wyjcie. Poniewa argumenty wyjciowe nie s modyfikowane jeli wywoanie
zawiedzie, argumenty nie zawsze mog zosta zdereferencjonowane. Na przykad
prba ``ls \-l'' na nieistniejcym pliku da nastpujc lini:
.CW
lstat("/foo/bar", 0xb004) = -1 ENOENT (No such file or directory)
.CE
.LP
Wskaniki znakowe s dereferencjonowane i wywietlane jako napisy C.
Niedrukowalne znaki s reprezentowane w kodach eskejpowych.
Drukowanych jest tylko pierwszych
.I rozmiarnapisu
(domylnie 32) bajtw napisu;
dusze napisy maj za zamykajcym cytatem doczone wielokropki.
Oto przykad ``ls \-l'', gdzie funkcja biblioteki getpwuid odczytuje plik z
hasem:
.CW
read(3, "root::0:0:System Administrator:/"..., 1024) = 422
.CE
\fRPodczas gdy struktury s notowane przy uyciu nawiasw klamrowych, zwyke
wskaniki i tablice s drukowane przy uyciu nawiasw kwadratowych, z
przecinkami oddzielajcymi elementy. Oto przykad wywoania komendy ``id''
na systemie z dodatkowymi id grup:
.CW
getgroups(32, [100, 0]) = 2
.CE
\fRZ drugiej strony, zbiory bitowe te s pokazywane w nawiasach kwadratowych,
lecz elementy s oddzielane tylko przez spacj. Oto powoka, przygotowujca
si do wywoania komendy zewntrznej:
.CW
sigprocmask(SIG_BLOCK, [CHLD TTOU], []) = 0
.CE
\fRDrugi argument jest zbiorem bitowym dwch sygnaw, SIGCHLD i SIGTTOU.
W niektrych wypadkach, zbiory bitowe s tak pene, e bardziej sensowne
jest drukowanie nieustawionych elementw. W takiej sytuacji zbir jest
poprzedzony tyld, jak w nastpujcym przykadzie:
.CW
sigprocmask(SIG_UNBLOCK, ~[], NULL) = 0
.CE
\fRDrugi argument wskazuje, e ustawiono cay zestaw sygnaw.
.SH OPCJE
.TP 12
.TP
.B \-c
Zliczaj czas, wywoania i bdy dla kadego wywoania systemowego i zgo na
kocu raport.
.TP
.B \-d
Przeka na
.I stderr 
wyjcie debuggowe strace.
.TP
.B \-f
led procesy potomne, tworzone prze obecnie ledzone procesy, jako rezultat
wywoania systemowego fork(2). Nowe procesy s doczane tak szybko, jak
szybko zostaje uzyskany ich pid (poprzez warto zwracan fork(2) w procesie
rodzicielskim). Oznacza to, e takie dzieci mog na chwil by
niekontrolowane (szczeglnie w wypadku vfork(2)), a rodzic nie zostanie
znw wyshedulowany do dokoczenia wywoania (v)fork(2).
Jeli rodzic zdecyduje zaczeka (wait(2)) na dziecko, ktre obecnie jest
ledzone, zostaje on zawieszony a potomek si nie zakoczy.
.TP
.B \-ff
opcja
.B \-o
.I nazwapliku
bdzie dziaa, ledzenie kadego procesu jest zapisywane do
.IR nazwapliku.pid ,
gdzie pid jest numerycznym identyfikatorem procesu.
.TP
.B \-F
Na SunOS 4.x opcja ta powoduje prb podania za vforkami poprzez triki
dynamicznego linkowania. W przeciwnym wypadku, vforki nie bd ledzone,
nawet z podan opcj
.BR \-f .
.TP
.B \-h
Wydrukuj podsumowanie pomocy.
.TP
.B \-i
Drukuj podczas wywoania systemowego wskanik instrukcji.
.TP
.B \-q
Zahamuj komunikaty o przyczaniu, odczaniu, etc. Dzieje si to
automatycznie gdy wyjcie jest przekierowywane do pliku, a komenda jest
wykonywana bezporednio, zamiast przyczania.
.TP
.B \-r
Drukuj wzgldny timestamp podczas kadego wywoania systemowego. Nagruwa to
rnic czasu midzy pocztkami kolejnych wywoa systemowych.
.TP
.B \-t
Poprzed kad lini trace czasem dnia.
.TP
.B \-tt
Jeli podane dwukrotnie, wydrukowany czas wcza mikrosekundy.
.TP
.B \-ttt
Jeli podane trzykrotnie, wydrukowany czas wcza mikrosekundy, a prowadzca
porcja bdzie zawiera liczb sekund od epoki.
.TP
.B \-T
Poka czas spdzony na wywoaniach systemowych. Nagrywa to rnice czasowe
midzy pocztkiem i kocem kadego wywoania systemowego.
.TP
.B \-v
Drukuj nieskrcone wersje wywoa environment, stat, termios, itp. 
Struktury te s wsplne w wywoaniach, wic domylne zachowanie wywietla
rozsdny podzbir czonkw. Gdy uzyjesz tej opcji, wywietlone zostanie
wszystko.
.TP
.B \-V
Wydrukuj numer wersji strace.
.TP
.B \-x
Drukuj wszystkie niedrukowalne napisy w formacie szesnastkowym.
.TP
.B \-xx
Drukuj wszystkie napisy w formacie szesnastkowym.
.TP
.BI "\-a " kolumna
Justuj zwracane wartoci w konkretnej kolumnie (domylnie 40).
.TP
.BI "\-e " wyra
Wyraenie kwalifikujce, okrelajce ktre zdarzenia ledzi, lub jak je
ledzi. Formatem wyraenia jest:
.br
[kwalifikator=][!]warto1[,warto2]...
.br
gdzie kwalifikator jest jednym z trace, abbrev, verbose, raw, signal, read,
lub write, a warto jest zalenaym od kwalifikatora symbolem, lub liczb.
Domylnym kwalifikatorem jest trace (led). Uycie wykrzyknika neguje zbir
wartoci. Na przykad \-eopen oznacza \-e trace=open, co z kolei oznacza, by
ledzi tylko wywoania systemowe open. Odwrotnie, \-etrace=!open oznacza,
by ledzi wszystkie wywoania poza wywoaniami open. Dodatkowo, istniej
specjalne wartoci all (wszystko) i none (nic).
.LP
Zauwa, e niektre powoki uywaj wykrzyknika dla rozszerzenia histori;
nawet wewntrz cytowanych argumentw. Jeli tak bdzie, musisz wyeskejpowa
wykrzyknik odwrotnym ukonikiem.
.TP
.BI "\-e trace=" zbir
led tylko podany zbir wywoa systemowych. Opcja
.B \-c
jest uyteczna dla okrelania, ktre wywoania systemowe mog by uyteczne
do ledzenia. Na przykad trace=open,close,read,write oznacza, by ledzi
tylko te cztery wywoania systemowe. Uwaaj z wyciganiem wnioskw o ramce
uytkownik/jdro jeli monitorujesz tylko podzbir uywanych wywoa
systemowych. Domylnie, trace=all.
.TP
.B "\-e trace=file"
led wszystkie wywoania systemowe, ktre bior nazw pliku jako argument.
Moesz myle o tym jak o skrcie dla
.BR "\-e trace=open,stat,chmod,unlink," ...
co moe by uyteczne dla sprawdzenia, ktre pliki s wane dla procesu.
Co wicej, uycie skrtu zapewni, e przypadkiem nie zapomnisz doczy
wywoania w rodzaju
.BR lstat .
.TP
.B "\-e trace=process"
led wszystkie wywoania systemowe, ktre zajmuj si zarzdzaniem
procesami. Jest to przydatne do obserwowania krokw fork, wait i exec
procesu.
.TP
.B "\-e trace=network"
led wszystkie wywoania zwizane z sieci.
.TP
.B "\-e trace=signal"
led wszystkie wywoania zwizane z sygnaami.
.TP
.B "\-e trace=ipc"
led wszystkie wywoania zwizane z IPC.
.TP
.BI "\-e abbrev=" zbir
Skr wyjcie przez niedrukowanie kadego czonka duych struktur.
Domylnie abbrev=all. Opcja
.B \-v
ma efekt abbrev=none.
.TP
.BI "\-e verbose=" zbir
Dereferencjuj struktury podanego zestawu wywoa systemowych. Domylnie jest
verbose=all.
.TP
.BI "\-e raw=" zbir
Drukuj czyste, niezdekodowane argumenty podanych wywoa systemowych. Opcja
te powoduje, e wszystkie argumenty s drukowane szesnastkowo. Jest to
najbardziej uyteczne, jeli nie ufasz dekodowaniu, lub jeli potrzebujesz
zna waciwe wartoci numeryczne argumentw.
.TP
.BI "\-e signal=" zbir
led tylko podany zbir sygnaw. Domylnie jest signal=all. Na przykad
signal=!SIGIO (lub signal=!io) powoduje, e sygnay SIGIO nie bd ledzone.
.TP
.BI "\-e read=" zbir
Dokonuj zrzutw szesnastkowych i ascii wszystkich danych odczytywanych z
deskryptorw podanych w zbiorze. Na przykad, by zobaczy co dzieje si na
wejciu deskryptorw 3, 5, uyj:
.BR "\-e read=3,5" .
Zauwa, e jest to niezalene od normalnego ledzenia wywoania read, ktre
jest kontrolowane opcj
.BR "\-e trace=read" .
.TP
.BI "\-e write=" zbir
Dokonuj zrzutw szesnastkowych i ascii wszystkich danych zapisywanych do
deskryptorw podanych w zbiorze. Na przykad, by zobaczy co dzieje si na
wyjciu deskryptorw 3, 5, uyj:
.BR "\-e write=3,5" .
Zauwa, e jest to niezalene od normalnego ledzenia wywoania write, ktre
jest kontrolowane opcj
.BR "\-e trace=write" .
.TP
.BI "\-o " nazwapliku
Zapisuj wyjcie ledzenia do pliku
.IR nazwapliku ,
a nie na standardowy bd.
Uyj
.I nazwapliku.pid
jeli uyto opcji
.BR \-ff .
Jesli argument zaczyna si od `|' lub od `!', reszta argumentu traktowana
jest jak komenda i cae wyjcie jest do niej przesyane. Jest to przydatne
dla przekierowywania wyjcia debuggowego, nie dotykajc przekierowa
normalnego wyjcia programu.
.TP
.BI "\-O " wydatki
Ustaw wydatki na ledzenie wywoa systemowych na wydatki mikrosekund.
Jest to uyteczne dla przecienia domylnej heurystyki dla zgadywania ile
czasu jest spdzanego na czystym mierzeniu podczas timingowaniu wywoa
systemowych przy uyciu opcji
.BR \-c .
Dokadno heurystyki moe by ocenione przez timingowanie danego programu
bez ledzenia i porwnanie zebranego czasu wywoa systemowych do
cakowitego, wydanego przy uyciu
.B \-c .
.TP
.BI "\-p " pid
Podwie si do procesu o podanym identyfikatorze
.SM ID
.I pid
i rozpocznij ledzenie.
ledzenie moe by zakoczone w dowolnym momencie przez przerwanie z
klawiatury (\c
.SM CTRL\s0-C).
.B strace
odpowie przez odwieszenie si od ledzonego procesu(w), pozostawiajc go
(je) w spokoju.
Do podwieszenia si do kolejnych 32 procesw, mona uywa wielu opcji
.BR \-p ,
jako uzupenienie komendy
.I komenda
(ktra jest opcjonalna, jeli podano przynajmniej jedn opcj
.BR \-p ).
.TP
.BI "\-s " wielkonapisu
Podaj maksymaln dugo drukowanego napisu (domylnie 32). Zauwa, e
nazwy plikw nie s uwaane za napisy i zawsze s drukowane w caoci.
.TP
.BI "\-S " sortuj
Sotruj wyjciowy histogram opcji
.B \-c
wedug podanego kryterium. Legalnymi wartociami s
time, calls, name, i nothing (domylne to time).
.TP
.BI "\-u " uytkownik
Uruchom komend z userid i groupid, oraz dodatkowymi grupami
.IR uytkownika .
Opcja ta jest uyteczna tylko podczas pracy z roota i umoliwia waciwe
wywoanie binariw z ustawionymi sgid/suid.
Bez tej opcji, programy suid/sgid s wywoywane bez efektywnych przywilejw.
.SH "INSTALACJA SETUID"
Jeli
.B strace
jest zainstalowane z suid root, to uytkownik wywoujcy bdzie mg si
podczy i ledzi procesy dowolnego innego uytkownika.
Dodatkowo, programy suid i sgid bd wywoywane i ledzonez waciwymi
efektywnymi przywilejami. Poniewa robi to powinni tylko zaufani
uytkownicy z przywilejami roota, takie instalowanie
.B strace
ma sens tylko, jeli uytkownicy uprawnieni do jego wywoywania maj
odpowiednie przywileje. Na przykad sensowne jest instalowanie specjalnej
wersji
.B strace
z prawami `rwsr-xr--', dla uytkownika root i grupy trace, gdzie czonkowie
grupy trace s zaufanymi osobami. Jeli uywasz tej waciwoci, pamitej by
zainstalowa niesuidowan wersj strace dla zwykych luserw.
.SH "ZOBACZ TAKE"
.BR ptrace(2) ,
.BR proc(4) ,
.BR time(1) ,
.BR trace(1) ,
.BR truss(1)
.SH UWAGI
Szkoda, e w systemach z bibliotekami dzielonym jest produkowanych tyle
mieci podczas ledzenia.
.LP
Jest dobrze myle o wejciach i wyjciach wywoa systemowych jak o
przepywie danych midzy przestrzeni uytkownika i jdra. Poniewa
przestrze uytkownika i przestrze jdra s oddzielone granic ochrony
adresw, mona czasem wyciga wnioski dedukcyjne o zachowaniu procesu na
podstawie wartoci wejcia i wyjcia.
.LP
W niektrych wypadkach wywoanie systemowe moe rni si od
udokumentowanego zachowania, lub mie inn nazw. Na przykad na systemach
zgodnych z System V, rzeczywiste wywoanie time(2) nie pobiera argumentu, a
funkcja stat nazywana jest xstat i bierze dodatkowy argument. 
Rnice te s normalne, lecz uczulone charakterystyki interfejsu wywoa
systemowych s obsugiwane przez wrappery biblioteki C.
.LP
Na niektrych platformach proces, ktry ma zaczone ledzenie wywoa
systemowych z opcj
.B \-p
otrzyma
.BR \s-1SIGSTOP\s0 .
Sygna ten moe przerwa wywoanie systemowe, ktre nie jest restartowalne.
Moe to mie nieprzewidziane efekty na procesie, jeli proces nie podejmuje
dziaa do restartowania wywoania systemowego.
.SH BDY
Programy, ktre uywaj bitu
.I setuid
nie bd miay efektywnych uprawnie uytkownika podczas ledzenia.
.LP
ledzony proces ignoruje
.SM SIGSTOP
(poza platformami SVR4).
.LP
ledzony proces, prbujcy zablokowa SIGTRAP otrzyma SIGSTOP w prbie
kontynuacji ledzenia.
.LP
ledzony program dziaa powoli.
.LP
ledzone procesy, ktre schodz z komendy
.I komenda
mog zosta pozostawione po sygnale przerwania (\c
.SM CTRL\s0-C).
.LP
Pod Linuksem, ledzenie procesu init jest zabronione.
.LP
Opcja
.B \-i
jest sabo wspierana.
.SH HISTORIA
.B strace
Oryginalny strace zosta napisany przez Paula Kranenburga
dla SunOS, ktry zosta zinspirowany narzdziem trace.
Wersja SunOS strace zostaa przeniesiona na Linuksa i rozszerzona przez
Branko Lankestera, ktry rwnie napisa wsparcie jdra Linuksa.
Mimo, e Paul w 1992 wypuci wersj 2.5 strace, prace Branko opieray si
na strace 1.5 z 1991. W 1993 Rick Sladkey poczy zmiany strace 2.5 z SunOS
ze zmianami wersji linuksowej, doda wiele waciwoci z truss'a z SVR4 i
wyda wersj strace, ktra dziaaa na obydwu platformach. W 1994 Rick
przeportowa strace na SVR4 i Solaris, oraz napisa wsparcie automatycznej
konfiguracji. W 1995 przeportowa strace na Irixa i zmczy si pisaniem 
o sobie w trzeciej osobie.
.SH PROBLEMY
Problemy zwizane ze
.B strace
powinny by zgaszane do obecnego opiekuna
.BR strace ,
ktrym jest Rick Sladkey <jrs@world.std.com>.