From c22bbbe9d60bf9404719d3fc5e4be549faef814f Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Mon, 8 Oct 2018 19:22:21 -0700 Subject: Make dbus-binding-tool.1 man page less Solaris specific Remove some old bits like Solaris 10 package name that's not even relevant on current Solaris releases. v2: Remove reference to non-existent libdbus-glib-1(3) man page Signed-off-by: Alan Coopersmith --- configure.ac | 1 + doc/Makefile.am | 2 - doc/dbus-binding-tool.1 | 294 --------------------------------------------- doc/dbus-binding-tool.1.in | 277 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 278 insertions(+), 296 deletions(-) delete mode 100644 doc/dbus-binding-tool.1 create mode 100644 doc/dbus-binding-tool.1.in diff --git a/configure.ac b/configure.ac index af73eae..e00bc38 100644 --- a/configure.ac +++ b/configure.ac @@ -296,6 +296,7 @@ AC_CONFIG_FILES([ Makefile m4/Makefile doc/Makefile +doc/dbus-binding-tool.1 doc/reference/Makefile doc/reference/version.xml dbus/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am index 9e6f5cb..27119fa 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,3 @@ SUBDIRS=reference man_MANS = dbus-binding-tool.1 - -EXTRA_DIST = $(man_MANS) \ No newline at end of file diff --git a/doc/dbus-binding-tool.1 b/doc/dbus-binding-tool.1 deleted file mode 100644 index 391c87c..0000000 --- a/doc/dbus-binding-tool.1 +++ /dev/null @@ -1,294 +0,0 @@ -'\" te -.TH dbus-binding-tool 1 "26 Feb 2009" "SunOS 5.11" "User Commands" -.SH "NAME" -dbus-binding-tool \- C language GLib bindings generation utility\&. -.SH "SYNOPSIS" -.PP -\fBdbus-binding-tool\fR [-\fB-force\fR] [-\fB-help\fR] [-\fB-ignore-unsupported\fR] [-\fB-mode=\fIpretty|glib-client|glib-server\fR\fR] [-\fB-output=\fIfile\fR\fR] [-\fB-prefix=\fIsymbol-prefix\fR\fR] [-\fB-version\fR] [\fB\fIfile\fR\fR\&...] -.SH "DESCRIPTION" -.PP -\fBdbus-binding-tool\fR is used to expose a GObject via D\-Bus\&. As input, -\fBdbus-binding-tool\fR uses a D\-Bus Introspection XML file\&. As output, -the client-side or server-side bindings is generated\&. This output is a header -file which eases the use of a remote D\-Bus object\&. Output is sent to standard -out or to the filename specified with the -\fB-output\fR argument\&. -.SH "EXTENDED DESCRIPTION" -.SS "" -.PP -The following is a sample D\-Bus Introspection XML file which describes an -object that exposes one method, named ManyArgs: -.PP -.nf - - - - - - - - - - - - -.fi -.PP -\fBdbus-binding-tool\fR supports annotations in the XML format to further -control how the bindings are generated\&. -.SS "client-side bindings" -.PP -When building client-side bindings, the -\fB-mode=glib-client\fR -argument is used\&. The client-side bindings support the -"org\&.freedesktop\&.DBus\&.Glib\&.NoReply" annotation\&. This is specified -within the tag to indicate that the client is not expecting -a reply to the method call, so a reply should not be sent\&. This is -often used to speed up rapid method calls where there are no "out" -arguments, and not knowing if the method succeeded is an acceptable compromise -to halve the traffic on the bus\&. For example: -.PP -.nf - - [\&.\&.\&.] - - [\&.\&.\&.] - -.fi -.SS "server-side bindings" -.PP -When building server-side bindings, the -\fB-mode=glib-server\fR -argument is used\&. Also the -\fB-prefix\fR argument must be used when -building server-side bindings so that functions in the generated output are -prefexed with the specified value\&. The server-side bindings support the -following annotations: -.PP -"org\&.freedesktop\&.DBus\&.GLib\&.CSymbol" -.PP -This annotation is used to specify the C symbol names for the various types -(interface, method, etc\&.), if it differs from the name D\-Bus generates\&. -.PP -.PP -.nf - - - [\&.\&.\&.] - - - [\&.\&.\&.] - - -.fi -.PP -"org\&.freedesktop\&.DBus\&.GLib\&.Async" -.PP -This annotation marks the method implementation as an asynchronous function, -which does not return a response straight away but will send the response at -some later point to complete the call\&. This is used to implement non-blocking -services where method calls can take time\&. -.PP -When a method is asynchronous, the function prototype is different\&. It is -required that the function conform to the following rules: -.sp -.in +2 -\(bu -.mk -.in +3 -.rt -The function must return a value of type gboolean; TRUE on success, -and FALSE otherwise\&. -.in -3 -\(bu -.mk -.in +3 -.rt -The first parameter is a pointer to an instance of the object\&. -.in -3 -\(bu -.mk -.in +3 -.rt -Following the object instance pointer are the method input values\&. -.in -3 -\(bu -.mk -.in +3 -.rt -The final parameter must be a (DBusGMethodInvocation *)\&. This is used -when sending the response message back to the client, by calling -dbus_g_method_return or dbus_g_method_return_error\&. -.in -3 -.in -2 -.PP -For example: -.PP -.nf - - [\&.\&.\&.] - - [\&.\&.\&.] - -.fi -.PP -"org\&.freedesktop\&.DBus\&.GLib\&.Const" -.PP -This attribute can only be applied to "out" nodes, and -specifies that the parameter is not being copied when returned\&. For example, -this turns a \&'s\&' argument from a (char **) to a (const char **), and results in -the argument not being freed by D\-Bus after the message is sent\&. For example: -.PP -.nf - - - -.fi -.PP -"org\&.freedesktop\&.DBus\&.GLib\&.ReturnVal" -.PP -This attribute can only be applied to "out" nodes, and -alters the expected function signature\&. It currently can be set to two values: -"" or "error"\&. The argument marked with this attribute is -not returned via a pointer argument, but by the function\&'s return value\&. If the -attribute\&'s value is the empty string, the (GError *) argument is also omitted -so there is no standard way to return an error value\&. This is very useful for -interfacing with existing code, as it is possible to match existing APIs\&. If -the attribute\&'s value is "error", then the final argument is a -(GError *) as usual\&. For example: -.PP -.nf - - - -.fi -.SH "OPTIONS" -.PP -The following options are supported: -.sp -.ne 2 -.mk -\fB-\fB-force\fR\fR -.sp .6 -.in +4 -Overwrite the output file if it already exists with a newer timestamp than the -source files\&. -.sp -.sp 1 -.in -4 -.sp -.ne 2 -.mk -\fB-\fB-help\fR\fR -.sp .6 -.in +4 -Display usage information\&. -.sp -.sp 1 -.in -4 -.sp -.ne 2 -.mk -\fB-\fB-ignore-unsupported\fR\fR -.sp .6 -.in +4 -If set, then unsupported signatures for parameters are -ignored\&. -.sp -.sp 1 -.in -4 -.sp -.ne 2 -.mk -\fB-\fB-mode=\fIpretty|glib-client|glib-server\fR\fR\fR -.sp .6 -.in +4 -If the value is "glib-client", then client bindings are generated\&. -If the value is "glib-server", then server bindings are generated\&. -If the value is "pretty", then the output is in a more human readable -format\&. -.sp -.sp 1 -.in -4 -.sp -.ne 2 -.mk -\fB-\fB-output=\fIfile\fR\fR\fR -.sp .6 -.in +4 -Specify the output \fIfile\fR\&. -.sp -.sp 1 -.in -4 -.sp -.ne 2 -.mk -\fB-\fB-prefix=\fIsymbol-prefix\fR\fR\fR -.sp .6 -.in +4 -Functions in the generated output are prefixed with the -\fIsymbol-prefix\fR value\&. -.sp -.sp 1 -.in -4 -.sp -.ne 2 -.mk -\fB-\fB-version\fR\fR -.sp .6 -.in +4 -Display the version number of the \fBdbus-binding-tool\fR command\&. -.sp -.sp 1 -.in -4 -.SH "OPERANDS" -.PP -The following operands are supported: -.sp -.ne 2 -.mk -\fB\fB\fIfile\fR\fR\fR -.in +16n -.rt -A list of one or more input D\-Bus Introspection XML files to include in the -generated output\&. -.sp -.sp 1 -.in -16n -.SH "FILES" -.PP -The following files are used by this application: -.sp -.ne 2 -.mk -\fB\fB/usr/bin/dbus-binding-tool\fR \fR -.in +32n -.rt -Executable for the D\-Bus Binding Tool application\&. -.sp -.sp 1 -.in -32n -.SH "ATTRIBUTES" -.PP -See \fBattributes\fR(5) -for descriptions of the following attributes: -.sp -.TS -tab() allbox; -cw(2.750000i)| cw(2.750000i) -lw(2.750000i)| lw(2.750000i). -ATTRIBUTE TYPEATTRIBUTE VALUE -AvailabilitySUNWdbus-bindings -Interface stabilityVolatile -.TE -.sp -.SH "SEE ALSO" -.PP -\fBdbus-cleanup-sockets\fR(1), -\fBdbus-daemon\fR(1), -\fBdbus-monitor\fR(1), -\fBdbus-send\fR(1), -\fBdbus-uuidgen\fR(1), -\fBlibdbus-glib-1\fR(3), -\fBattributes\fR(5) -.SH "NOTES" -.PP -Written by Brian Cameron, Sun Microsystems Inc\&., 2009\&. -...\" created by instant / solbook-to-man, Thu 26 Feb 2009, 19:15 -...\" LSARC 2006/368 D-BUS Message Bus System diff --git a/doc/dbus-binding-tool.1.in b/doc/dbus-binding-tool.1.in new file mode 100644 index 0000000..5591fc2 --- /dev/null +++ b/doc/dbus-binding-tool.1.in @@ -0,0 +1,277 @@ +'\" te +.TH dbus-binding-tool 1 "8 Oct 2018" "@PACKAGE_STRING@" "User Commands" +.SH "NAME" +dbus-binding-tool \- C language GLib bindings generation utility\&. +.SH "SYNOPSIS" +.PP +\fBdbus-binding-tool\fR [-\fB-force\fR] [-\fB-help\fR] [-\fB-ignore-unsupported\fR] [-\fB-mode=\fIpretty|glib-client|glib-server\fR\fR] [-\fB-output=\fIfile\fR\fR] [-\fB-prefix=\fIsymbol-prefix\fR\fR] [-\fB-version\fR] [\fB\fIfile\fR\fR\&...] +.SH "DESCRIPTION" +.PP +\fBdbus-binding-tool\fR is used to expose a GObject via D\-Bus\&. As input, +\fBdbus-binding-tool\fR uses a D\-Bus Introspection XML file\&. As output, +the client-side or server-side bindings is generated\&. This output is a header +file which eases the use of a remote D\-Bus object\&. Output is sent to standard +out or to the filename specified with the -\fB-output\fR argument\&. +.SH "EXTENDED DESCRIPTION" +.SS "" +.PP +The following is a sample D\-Bus Introspection XML file which describes an +object that exposes one method, named ManyArgs: +.PP +.nf + + + + + + + + + + + + +.fi +.PP +\fBdbus-binding-tool\fR supports annotations in the XML format to further +control how the bindings are generated\&. +.SS "client-side bindings" +.PP +When building client-side bindings, the -\fB-mode=glib-client\fR +argument is used\&. The client-side bindings support the +"org\&.freedesktop\&.DBus\&.Glib\&.NoReply" annotation\&. This is specified +within the tag to indicate that the client is not expecting +a reply to the method call, so a reply should not be sent\&. This is +often used to speed up rapid method calls where there are no "out" +arguments, and not knowing if the method succeeded is an acceptable compromise +to halve the traffic on the bus\&. For example: +.PP +.nf + + [\&.\&.\&.] + + [\&.\&.\&.] + +.fi +.SS "server-side bindings" +.PP +When building server-side bindings, the -\fB-mode=glib-server\fR +argument is used\&. Also the -\fB-prefix\fR argument must be used when +building server-side bindings so that functions in the generated output are +prefexed with the specified value\&. The server-side bindings support the +following annotations: +.PP +"org\&.freedesktop\&.DBus\&.GLib\&.CSymbol" +.PP +This annotation is used to specify the C symbol names for the various types +(interface, method, etc\&.), if it differs from the name D\-Bus generates\&. +.PP +.PP +.nf + + + [\&.\&.\&.] + + + [\&.\&.\&.] + + +.fi +.PP +"org\&.freedesktop\&.DBus\&.GLib\&.Async" +.PP +This annotation marks the method implementation as an asynchronous function, +which does not return a response straight away but will send the response at +some later point to complete the call\&. This is used to implement non-blocking +services where method calls can take time\&. +.PP +When a method is asynchronous, the function prototype is different\&. It is +required that the function conform to the following rules: +.sp +.in +2 +\(bu +.mk +.in +3 +.rt +The function must return a value of type gboolean; TRUE on success, +and FALSE otherwise\&. +.in -3 +\(bu +.mk +.in +3 +.rt +The first parameter is a pointer to an instance of the object\&. +.in -3 +\(bu +.mk +.in +3 +.rt +Following the object instance pointer are the method input values\&. +.in -3 +\(bu +.mk +.in +3 +.rt +The final parameter must be a (DBusGMethodInvocation *)\&. This is used +when sending the response message back to the client, by calling +dbus_g_method_return or dbus_g_method_return_error\&. +.in -3 +.in -2 +.PP +For example: +.PP +.nf + + [\&.\&.\&.] + + [\&.\&.\&.] + +.fi +.PP +"org\&.freedesktop\&.DBus\&.GLib\&.Const" +.PP +This attribute can only be applied to "out" nodes, and +specifies that the parameter is not being copied when returned\&. For example, +this turns a \&'s\&' argument from a (char **) to a (const char **), and results in +the argument not being freed by D\-Bus after the message is sent\&. For example: +.PP +.nf + + + +.fi +.PP +"org\&.freedesktop\&.DBus\&.GLib\&.ReturnVal" +.PP +This attribute can only be applied to "out" nodes, and +alters the expected function signature\&. It currently can be set to two values: +"" or "error"\&. The argument marked with this attribute is +not returned via a pointer argument, but by the function\&'s return value\&. If the +attribute\&'s value is the empty string, the (GError *) argument is also omitted +so there is no standard way to return an error value\&. This is very useful for +interfacing with existing code, as it is possible to match existing APIs\&. If +the attribute\&'s value is "error", then the final argument is a +(GError *) as usual\&. For example: +.PP +.nf + + + +.fi +.SH "OPTIONS" +.PP +The following options are supported: +.sp +.ne 2 +.mk +\fB-\fB-force\fR\fR +.sp .6 +.in +4 +Overwrite the output file if it already exists with a newer timestamp than the +source files\&. +.sp +.sp 1 +.in -4 +.sp +.ne 2 +.mk +\fB-\fB-help\fR\fR +.sp .6 +.in +4 +Display usage information\&. +.sp +.sp 1 +.in -4 +.sp +.ne 2 +.mk +\fB-\fB-ignore-unsupported\fR\fR +.sp .6 +.in +4 +If set, then unsupported signatures for parameters are +ignored\&. +.sp +.sp 1 +.in -4 +.sp +.ne 2 +.mk +\fB-\fB-mode=\fIpretty|glib-client|glib-server\fR\fR\fR +.sp .6 +.in +4 +If the value is "glib-client", then client bindings are generated\&. +If the value is "glib-server", then server bindings are generated\&. +If the value is "pretty", then the output is in a more human readable +format\&. +.sp +.sp 1 +.in -4 +.sp +.ne 2 +.mk +\fB-\fB-output=\fIfile\fR\fR\fR +.sp .6 +.in +4 +Specify the output \fIfile\fR\&. +.sp +.sp 1 +.in -4 +.sp +.ne 2 +.mk +\fB-\fB-prefix=\fIsymbol-prefix\fR\fR\fR +.sp .6 +.in +4 +Functions in the generated output are prefixed with the +\fIsymbol-prefix\fR value\&. +.sp +.sp 1 +.in -4 +.sp +.ne 2 +.mk +\fB-\fB-version\fR\fR +.sp .6 +.in +4 +Display the version number of the \fBdbus-binding-tool\fR command\&. +.sp +.sp 1 +.in -4 +.SH "OPERANDS" +.PP +The following operands are supported: +.sp +.ne 2 +.mk +\fB\fB\fIfile\fR\fR\fR +.in +16n +.rt +A list of one or more input D\-Bus Introspection XML files to include in the +generated output\&. +.sp +.sp 1 +.in -16n +.SH "FILES" +.PP +The following files are used by this application: +.sp +.ne 2 +.mk +\fB\fB@bindir@/dbus-binding-tool\fR \fR +.in +32n +.rt +Executable for the D\-Bus Binding Tool application\&. +.sp +.sp 1 +.in -32n +.SH "SEE ALSO" +.PP +\fBdbus-cleanup-sockets\fR(1), +\fBdbus-daemon\fR(1), +\fBdbus-monitor\fR(1), +\fBdbus-send\fR(1), +\fBdbus-uuidgen\fR(1) +.SH "NOTES" +.PP +Written by Brian Cameron, Sun Microsystems Inc\&., 2009\&. +...\" created by instant / solbook-to-man, Thu 26 Feb 2009, 19:15 -- cgit v1.2.1