For information about launching fidlcat: fidlcat.
{% dynamic if request.tld != “dev” %}
Notice
This file only renders correctly from fuchsia.dev. Please navigate to https://fuchsia.dev/fuchsia-src/development/monitor/fidlcat/fidlcat_usage.md to see the examples correctly!
{% dynamic endif %}
The default display for fidlcat is:
We have the following information:
echo_client_cpp_synchronous: the name of the application which has generated this display.
180768: the process koid.
180781: the thread koid.
zx_channel_call: the name of the intercepted/displayed system call.
all the basic input parameters of the system call (here handle and options).
For each one, we have:
The name of the parameter in black.
The type of the parameter in green.
The value of the parameter (the color depends on the parameter type).
all the complex input parameters. Here we display a FIDL message. This is a request which is sent by our application.
The display stops here. It will resume when the system call returns (sometimes it can be a very long time). For one thread, there will be no other display between the input arguments and the returned value. However, another thread display may be interleaved. When the system call returns, we display:
The returned value (-> ZX_OK)
The basic output parameters (there is no basic output parameters in this example).
The complex output parameters. Here we display a FIDL message. This is the response we received to the request we sent.
For zx_channel_read we can have this display:
But, if there is an error, we can have:
Or:
In this last case, even if the system call fails, we have some valid output parameters. actual_bytes and actual_handles give the minimal values which should have been used to call zx_channel_read.
By default, we only display the process information on the first line.
Eventually, we also display the process information before the returned value if a system call from another thread has been displayed between the call and the returned value:
Using the flag --with-process-info, we can display the process information on each line:
This is very useful if we want to do a grep on the output (for example, to only select one thread).
Most of the time we want to link several messages to be able to understand what our program is doing.
In this example:
We first create a channel. The two handles 0243b493 and 0163b42b are linked. That means that a write on one handle will result on a read on the other handle.
We use handle 0163b42b in the Directory.Open message. That means that the associated handle (0243b493) is the handle which controls the directory we just opened.
When we receive Node.OnOpen on 0243b493 we know that it's a response to our Directory.Open. We also used the handle to call Node.Close.
By default, only the system calls are displayed. However, it's sometime interesting to know where a system call has been called. Using the flag --stack we can display the stack frames for every system call.
By default (--stack=0), the stack frames are not displayed.
With --stack=1 only the call site (1 to 4 frames) is displayed:
This option doesn't add any overhead (except for the display).
With --stack=2 all the frames are displayed:
This option adds some overhead because we need to ask zxdb for the full stack for each system call (and fidlcat becomes even more verbose). You should use it only when you need to understand what part of your code called the system calls.
Sometimes, your program crashes. If it's monitored by fidlcat you automatically have a stack where it crashed.
For example:
You have the stack frames for the exception even if you didn't ask for the stack frames with the --stack options.
By default, fidlcat only displays the zx_channel syscalls.
You can display all the syscalls and choose which ones you want to display.
The --syscalls option let you define a regular expression which selects the syscalls to decode and display.
It can be passed multiple times.
To display all the syscalls, use: --syscalls=“.*”
The --exclude-syscalls flag lets you exclude some syscalls selected by --syscalls. It's a regular expression which selects the syscalls to not decode and display.
It can be passed multiple times.
To be displayed, a syscall must satisfy the --syscalls pattern and not satisfy the --exclude-syscalls pattern.
To display all the syscalls but the zx_handle syscalls, use:
--syscalls “.*” --exclude-syscalls “zx_handle_.*”
By default, fidlcat displays all the messages.
You can specify the messages you want to display using:
--messages allows you to specify one or more regular expressions the messages must satisfy to be displayed.
--exclude-messages allows you to specify one or more regular expressions the messages must not satisfy to be displayed.
If both options are used at the same time, to be displayed, a message must satisfy one of the regular expressions specified with --messages and not satisfy any regular expression specified with --exclude-messages.
Message filtering works on the method's fully qualified name. For example, with:
--messages=".*Open"
Methods like:
fuchsia.io/Directory.Open fuchsia.io/Node.OnOpen
Will match.
By default, everything is displayed as soon as an application is monitored. You can differ the display using --trigger. With this option the display will start only if one message satisfying one of the regular expressions specified with --trigger is encountered.
This is really useful when you need to understand what's going on after you received or emit a particular message.
Fidlcat can connect to a symbol server. You have to use the option:
--with-symbol-server
The first time you use this option, fidlcat will give you a link to an authentication page. You then have to use the generated key to authenticate.
Sometime, you don't need to display all the messages exchanged but only a high level view of the session. The options --with=summary and --with=summary=<path> generate a high level summary of the session.
With those options, fidlcat displays a list of all the monitored processes.
For each process, fidlcat displays a list of all the handles found for the process.
For each handle, fidlcat displays the information we have about the process. That includes the data fidlcat has been able to infer. It also display if the handle is a startup handle (inherited while the process has been created) or a handle created during the process life.
For channels, fidlcat tries to display the other end of the channel (even if the other end is own by another process).
For non startup handles, fidlcat displays how the handle was created:
by calling zx_channel_create, zx_port_create, zx_timer_create, ...
by receiving a handle within a message.
Then fidlcat displays a list of all the messages sent and received (only for channels).
Finally fidlcat displays how the handle was closed:
by calling zx_handle_close or zx_handle_close_many.
by sending the handle to another process.
If fidlcat doesn't display that a handle is closed, that probably means that the program forgot to close it.
The options --with=top and --with=top<path> generate a view that groups the output by process, protocol, and method. The groups are sorted by number of events, so groups with more associated events are listed earlier.
