diff options
Diffstat (limited to 'upstream/fedora-40/man1/varlinkctl.1')
| -rw-r--r-- | upstream/fedora-40/man1/varlinkctl.1 | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/varlinkctl.1 b/upstream/fedora-40/man1/varlinkctl.1 new file mode 100644 index 00000000..61b4aa3c --- /dev/null +++ b/upstream/fedora-40/man1/varlinkctl.1 @@ -0,0 +1,324 @@ +'\" t +.TH "VARLINKCTL" "1" "" "systemd 255" "varlinkctl" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +varlinkctl \- Introspect with and invoke Varlink services +.SH "SYNOPSIS" +.HP \w'\fBvarlinkctl\fR\ 'u +\fBvarlinkctl\fR [OPTIONS...] info \fIADDRESS\fR +.HP \w'\fBvarlinkctl\fR\ 'u +\fBvarlinkctl\fR [OPTIONS...] list\-interfaces \fIADDRESS\fR +.HP \w'\fBvarlinkctl\fR\ 'u +\fBvarlinkctl\fR [OPTIONS...] introspect \fIADDRESS\fR \fIINTERFACE\fR +.HP \w'\fBvarlinkctl\fR\ 'u +\fBvarlinkctl\fR [OPTIONS...] call \fIADDRESS\fR \fIMETHOD\fR [\fIPARAMETERS\fR] +.HP \w'\fBvarlinkctl\fR\ 'u +\fBvarlinkctl\fR [OPTIONS...] validate\-idl [\fIFILE\fR] +.SH "DESCRIPTION" +.PP +\fBvarlinkctl\fR +may be used to introspect and invoke +\m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2 +services\&. +.PP +Services are referenced by one of the following: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A Varlink service reference starting with the +"unix:" +string, followed by an absolute +\fBAF_UNIX\fR +path, or by +"@" +and an arbitrary string (the latter for referencing sockets in the abstract namespace)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A Varlink service reference starting with the +"exec:" +string, followed by an absolute path of a binary to execute\&. +.RE +.PP +For convenience these two simpler (redundant) service address syntaxes are also supported: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A file system path to an +\fBAF_UNIX\fR +socket, either absolute (i\&.e\&. begins with +"/") or relative (in which case it must begin with +"\&./")\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A file system path to an executable, either absolute or relative (as above, must begin with +"/", resp\&. +"\&./")\&. +.RE +.SH "COMMANDS" +.PP +The following commands are understood: +.PP +\fBinfo\fR \fIADDRESS\fR +.RS 4 +Show brief information about the specified service, including vendor name and list of implemented interfaces\&. Expects a service address in the formats described above\&. +.sp +Added in version 255\&. +.RE +.PP +\fBlist\-interfaces\fR \fIADDRESS\fR +.RS 4 +Show list of interfaces implemented by the specified service\&. Expects a service address in the formats described above\&. +.sp +Added in version 255\&. +.RE +.PP +\fBintrospect\fR \fIADDRESS\fR \fIINTERFACE\fR +.RS 4 +Show interface definition of the specified interface provided by the specified service\&. Expects a service address in the formats described above and a Varlink interface name\&. +.sp +Added in version 255\&. +.RE +.PP +\fBcall\fR \fIADDRESS\fR \fIMETHOD\fR [\fIARGUMENTS\fR] +.RS 4 +Call the specified method of the specified service\&. Expects a service address in the format described above, a fully qualified Varlink method name, and a JSON arguments object\&. If the arguments object is not specified, it is read from STDIN instead\&. To pass an empty list of parameters, specify the empty object +"{}"\&. +.sp +The reply parameters are written as JSON object to STDOUT\&. +.sp +Added in version 255\&. +.RE +.PP +\fBvalidate\-idl\fR [\fIFILE\fR] +.RS 4 +Reads a Varlink interface definition file, parses and validates it, then outputs it with syntax highlighting\&. This checks for syntax and internal consistency of the interface\&. Expects a file name to read the interface definition from\&. If omitted reads the interface definition from STDIN\&. +.sp +Added in version 255\&. +.RE +.PP +\fBhelp\fR +.RS 4 +Show command syntax help\&. +.sp +Added in version 255\&. +.RE +.SH "OPTIONS" +.PP +The following options are understood: +.PP +\fB\-\-more\fR +.RS 4 +When used with +\fBcall\fR: expect multiple method replies\&. If this flag is set the method call is sent with the +\fBmore\fR +flag set, which tells the service to generate multiple replies, if needed\&. The command remains running until the service sends a reply message that indicates it is the last in the series\&. This flag should be set only for method calls that support this mechanism\&. +.sp +If this mode is enabled output is automatically switched to JSON\-SEQ mode, so that individual reply objects can be easily discerned\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-oneway\fR +.RS 4 +When used with +\fBcall\fR: do not expect a method reply\&. If this flag is set the method call is sent with the +\fBoneway\fR +flag set (the command exits immediately after), which tells the service not to generate a reply\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-json=\fR\fIMODE\fR +.RS 4 +Selects the JSON output formatting, one of +"pretty" +(for nicely indented, colorized output) or +"short" +(for terse output with minimal whitespace and no newlines), defaults to +"short"\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-j\fR +.RS 4 +Equivalent to +\fB\-\-json=pretty\fR +when invoked interactively from a terminal\&. Otherwise equivalent to +\fB\-\-json=short\fR, in particular when the output is piped to some other program\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-no\-pager\fR +.RS 4 +Do not pipe output into a pager\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print a short version string and exit\&. +.RE +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Investigating a Service\fR +.PP +The following three commands inspect the +"io\&.systemd\&.Resolve" +service implemented by +\fBsystemd-resolved.service\fR(8), listing general service information and implemented interfaces, and then displaying the interface definition of its primary interface: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ varlinkctl info /run/systemd/resolve/io\&.systemd\&.Resolve + Vendor: The systemd Project + Product: systemd (systemd\-resolved) + Version: 254 (254\-1522\-g4790521^) + URL: https://systemd\&.io/ +Interfaces: io\&.systemd + io\&.systemd\&.Resolve + org\&.varlink\&.service +$ varlinkctl list\-interfaces /run/systemd/resolve/io\&.systemd\&.Resolve +io\&.systemd +io\&.systemd\&.Resolve +org\&.varlink\&.service +$ varlinkctl introspect /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve +interface io\&.systemd\&.Resolve +type ResolvedAddress( + ifindex: ?int, + \&... +.fi +.if n \{\ +.RE +.\} +.PP +(Interface definition has been truncated in the example above, in the interest of brevity\&.) +.PP +\fBExample\ \&2.\ \&Invoking a Method\fR +.PP +The following command resolves a hostname via +\fBsystemd-resolved.service\fR(8)\*(Aqs +\fBResolveHostname\fR +method call\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ varlinkctl call /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve\&.ResolveHostname \*(Aq{"name":"systemd\&.io","family":2}\*(Aq \-j +{ + "addresses" : [ + { + "ifindex" : 2, + "family" : 2, + "address" : [ + 185, + 199, + 111, + 153 + ] + } + ], + "name" : "systemd\&.io", + "flags" : 1048577 +} +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&Investigating a Service Executable\fR +.PP +The following command inspects the +/usr/lib/systemd/systemd\-pcrextend +executable and the IPC APIs it provides\&. It then invokes a method on it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# varlinkctl info /usr/lib/systemd/systemd\-pcrextend + Vendor: The systemd Project + Product: systemd (systemd\-pcrextend) + Version: 254 (254\-1536\-g97734fb) + URL: https://systemd\&.io/ +Interfaces: io\&.systemd + io\&.systemd\&.PCRExtend + org\&.varlink\&.service +# varlinkctl introspect /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend +interface io\&.systemd\&.PCRExtend + +method Extend( + pcr: int, + text: ?string, + data: ?string +) \-> () +# varlinkctl call /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend\&.Extend \*(Aq{"pcr":15,"text":"foobar"}\*(Aq +{} +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBbusctl\fR(1), +\m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2 +.SH "NOTES" +.IP " 1." 4 +Varlink +.RS 4 +\%https://varlink.org/ +.RE |