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.
