diff options
Diffstat (limited to 'tools')
-rw-r--r-- | tools/Makefile.am | 23 | ||||
-rw-r--r-- | tools/common.c | 2 | ||||
-rw-r--r-- | tools/doc/consume.xml | 173 | ||||
-rw-r--r-- | tools/doc/get.xml | 95 | ||||
-rw-r--r-- | tools/doc/librabbitmq-tools.xml | 90 | ||||
-rw-r--r-- | tools/doc/publish.xml | 160 |
6 files changed, 542 insertions, 1 deletions
diff --git a/tools/Makefile.am b/tools/Makefile.am index dc9603b..307fbd2 100644 --- a/tools/Makefile.am +++ b/tools/Makefile.am @@ -10,3 +10,26 @@ noinst_HEADERS = common.h amqp_publish_SOURCES = publish.c common.c amqp_get_SOURCES = get.c common.c amqp_consume_SOURCES = consume.c common.c + +if TOOLS_DOC +man_MANS = doc/amqp-publish.1 doc/amqp-consume.1 doc/amqp-get.1 doc/librabbitmq-tools.7 +MOSTLYCLEANFILES = doc/man-date.ent + +# automake complains about % pattern rules, and suffix rules don't +# support multiple dependencies, so we have to expand all these out. +doc/amqp-publish.1: doc/publish.xml doc/man-date.ent + $(XMLTO) man -o doc $< +doc/amqp-consume.1: doc/consume.xml doc/man-date.ent + $(XMLTO) man -o doc $< +doc/amqp-get.1: doc/get.xml doc/man-date.ent + $(XMLTO) man -o doc $< +doc/librabbitmq-tools.7: doc/librabbitmq-tools.xml doc/man-date.ent + $(XMLTO) man -o doc $< + +doc/man-date.ent: + date +'%Y-%m-%d' >$@ + +clean:: + rm -f doc/man-date.ent + +endif diff --git a/tools/common.c b/tools/common.c index 37fd301..6a38a95 100644 --- a/tools/common.c +++ b/tools/common.c @@ -187,7 +187,7 @@ static char *amqp_password = "guest"; const char *connect_options_title = "Connection options"; struct poptOption connect_options[] = { {"server", 's', POPT_ARG_STRING, &amqp_server, 0, - "the AMQP server to connect to", "server"}, + "the AMQP server to connect to", "hostname:port"}, {"vhost", 0, POPT_ARG_STRING, &amqp_vhost, 0, "the vhost to use when connecting", "vhost"}, {"username", 0, POPT_ARG_STRING, &amqp_username, 0, diff --git a/tools/doc/consume.xml b/tools/doc/consume.xml new file mode 100644 index 0000000..448ade6 --- /dev/null +++ b/tools/doc/consume.xml @@ -0,0 +1,173 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd" +[ +<!ENTITY date SYSTEM "man-date.ent" > +] +> +<refentry lang="en"> + <refentryinfo> + <productname>RabbitMQ C Client</productname> + <authorgroup> + <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> + </authorgroup> + <date>&date;</date> + </refentryinfo> + + <refmeta> + <refentrytitle>amqp-consume</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>amqp-consume</refname> + <refpurpose>Consume messages from a queue on an AMQP server</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>amqp-consume</command> + <arg choice="opt" rep="repeat"> + <replaceable>OPTION</replaceable> + </arg> + <arg choice="req"> + <replaceable>command</replaceable> + </arg> + <arg choice="opt" rep="repeat"> + <replaceable>args</replaceable> + </arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + <command>amqp-consume</command> consumes messages from a + queue on an AMQP server. For each message that arrives, a + receiving command is run, with the message body supplied + to it on standard input. + </para> + <para> + <command>amqp-consume</command> can consume from an + existing queue, or it can create a new queue. It can + optionally bind the queue to an existing exchange, or to a + newly created exchange. + </para> + <para> + By default, messages will be consumed with explicit + acknowledgements. A message will only be acknowledged if + the receiving command exits successfully (i.e. with an + exit code of zero). The AMQP <quote>no ack</quote> mode + (a.k.a. auto-ack mode) can be enable with the + <option>-A</option> option. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + <variablelist> + <varlistentry> + <term><option>-q</option></term> + <term><option>--queue</option>=<replaceable class="parameter">queue name</replaceable></term> + <listitem> + <para> + The name of the queue to consume messages + from. If the specified queue does not exist, + an auto-delete queue is created with the given + name. If this option is omitted, a new + auto-delete queue will be created, with a + unique name assigned to the queue by the AMQP + server; that unique name will be displayed on + stderr. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-e</option></term> + <term><option>--exchange</option>=<replaceable class="parameter">exchange name</replaceable></term> + <listitem> + <para> + The name of the exchange to bind the queue to. + If omitted, binding is not performed. The + specified exchange should already exist unless + the <option>--exchange-type</option> option is + used to request the creation of an exchange. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-t</option></term> + <term><option>--exchange-type</option>=<replaceable class="parameter">type</replaceable></term> + <listitem> + <para> + This option indicates that an auto-delete + exchange of the specified type should be + created. The name of the exchange should be + given by the <option>--exchange</option> + option. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-r</option></term> + <term><option>--routing-key</option>=<replaceable class="parameter">routing key</replaceable></term> + <listitem> + <para> + The routing key for the binding. If omitted, + an empty routing key is assumed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-A</option></term> + <term><option>--no-ack</option>=<replaceable class="parameter">routing key</replaceable></term> + <listitem> + <para> + Enable <quote>no ack</quote> mode: The AMQP + server will unconditionally acknowledge each + message that is delivered, regardless of + whether the target command exits successfully + or not. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <variablelist> + <varlistentry> + <term>Consume messages from the queue + <quote><systemitem + class="resource">myqueue</systemitem></quote>, and + output the message bodies on standard output via + <command>cat</command>:</term> + <listitem> + <screen><prompt>$ </prompt><userinput>amqp-publish -q myqueue cat</userinput></screen> + </listitem> + </varlistentry> + + <varlistentry> + <term>Bind a newly created auto-delete queue to an + exchange <quote><systemitem + class="resource">myexch</systemitem></quote>, and send + each message body to the script + <filename>myscript</filename>, automatically + acknowledging them on the server:</term> + <listitem> + <screen><prompt>$ </prompt><userinput>amqp-consume -A -e myexch ./myscript</userinput></screen> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See also</title> + <para> + <citerefentry><refentrytitle>librabbitmq-tools</refentrytitle><manvolnum>7</manvolnum></citerefentry> + describes connection-related options common to all the + RabbitMQ C Client tools. + </para> + </refsect1> +</refentry> diff --git a/tools/doc/get.xml b/tools/doc/get.xml new file mode 100644 index 0000000..9770a8b --- /dev/null +++ b/tools/doc/get.xml @@ -0,0 +1,95 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd" +[ +<!ENTITY date SYSTEM "man-date.ent" > +] +> +<refentry lang="en"> + <refentryinfo> + <productname>RabbitMQ C Client</productname> + <authorgroup> + <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> + </authorgroup> + <date>&date;</date> + </refentryinfo> + + <refmeta> + <refentrytitle>amqp-get</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>amqp-get</refname> + <refpurpose>Get a message from a queue on an AMQP server</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>amqp-get</command> + <arg choice="opt" rep="repeat"> + <replaceable>OPTION</replaceable> + </arg> + <arg choice="req">-q <replaceable>queue name</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + <command>amqp-get</command> attempts to consume a single + message from a queue on an AMQP server, and exits. Unless + the queue was empty, the body of the resulting message is + sent to standard output. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + <variablelist> + <varlistentry> + <term><option>-q</option></term> + <term><option>--queue</option>=<replaceable class="parameter">queue name</replaceable></term> + <listitem> + <para> + The name of the queue to consume messages + from. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit Status</title> + <para> + If the queue is not empty, and a message is successfully + retrieved, the exit status is 0. If an error occurs, the + exit status is 1. If the queue is found to be empty, the + exit status is 2. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + <variablelist> + <varlistentry> + <term>Get a message from the queue <quote><systemitem + class="resource">myqueue</systemitem></quote>, and + display its body on standard output:</term> + <listitem> + <screen><prompt>$ </prompt><userinput>amqp-get -q myqueue</userinput></screen> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See also</title> + <para> + <citerefentry><refentrytitle>librabbitmq-tools</refentrytitle><manvolnum>7</manvolnum></citerefentry> + describes connection-related options common to all the + RabbitMQ C Client tools. + </para> + </refsect1> +</refentry> diff --git a/tools/doc/librabbitmq-tools.xml b/tools/doc/librabbitmq-tools.xml new file mode 100644 index 0000000..41f092a --- /dev/null +++ b/tools/doc/librabbitmq-tools.xml @@ -0,0 +1,90 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd" +[ +<!ENTITY date SYSTEM "man-date.ent" > +] +> +<refentry lang="en"> + <refentryinfo> + <productname>RabbitMQ C Client</productname> + <authorgroup> + <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> + </authorgroup> + <date>&date;</date> + </refentryinfo> + + <refmeta> + <refentrytitle>librabbitmq-tools</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>librabbitmq-tools</refname> + <refpurpose>Command line AMQP tools</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + <para> + A set of command line AMQP tools based on <systemitem + class="library">librabbitmq</systemitem>. This page + describes common options and conventions used by all of + the tools. + </para> + </refsect1> + + <refsect1> + <title>Common Options</title> + <variablelist> + <varlistentry> + <term><option>-s</option></term> + <term><option>--server</option>=<replaceable class="parameter">hostname:port</replaceable></term> + <listitem> + <para> + The host name (or address) to connect to. + Defaults to localhost. The port number may + also be specified; if omitted, it defaults to + the standard AMQP port number (5672). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--vhost</option>=<replaceable class="parameter">vhost</replaceable></term> + <listitem> + <para> + The AMQP vhost to specify when connnecting. + Defaults to <literal>/</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--username</option>=<replaceable class="parameter">username</replaceable></term> + <listitem> + <para> + The username to authenticate to the AMQP server with. Defaults to <literal>guest</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--password</option>=<replaceable class="parameter">password</replaceable></term> + <listitem> + <para> + The password to authenticate to the AMQP server with. Defaults to <literal>guest</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See also</title> + <para> + <simplelist type='inline'> + <member><citerefentry><refentrytitle>amqp-publish</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>amqp-consume</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>amqp-get</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + </simplelist> + </para> + </refsect1> +</refentry> diff --git a/tools/doc/publish.xml b/tools/doc/publish.xml new file mode 100644 index 0000000..d2e8d2e --- /dev/null +++ b/tools/doc/publish.xml @@ -0,0 +1,160 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd" +[ +<!ENTITY date SYSTEM "man-date.ent" > +] +> +<refentry lang="en"> + <refentryinfo> + <productname>RabbitMQ C Client</productname> + <authorgroup> + <corpauthor>The RabbitMQ Team <<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>></corpauthor> + </authorgroup> + <date>&date;</date> + </refentryinfo> + + <refmeta> + <refentrytitle>amqp-publish</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>amqp-publish</refname> + <refpurpose>Publish a message on an AMQP server</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>amqp-publish</command> + <arg choice="opt" rep="repeat"> + <replaceable>OPTION</replaceable> + </arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> + Publishes a message to an exchange on an AMQP server. + Options allow the various properties of the message and + parameters of the AMQP <function>basic.publish</function> + method to be specified. + </para> + <para> + By default, the message body is read from standard input. + Alternatively, the <option>-b</option> option allows the message + body to be provided as part of the command. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + <variablelist> + <varlistentry> + <term><option>-e</option></term> + <term><option>--exchange</option>=<replaceable class="parameter">exchange name</replaceable></term> + <listitem> + <para> + The name of the exchange to publish to. If + omitted, the default exchange (also known as + the nameless exchange) is used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-r</option></term> + <term><option>--routing-key</option>=<replaceable class="parameter">routing key</replaceable></term> + <listitem> + <para> + The routing key to publish with. If omitted, + an empty routing key is assumed. A routing + key must be specified when publishing to the + default exchange; in that case, accoding to + the AMQP specification, the routing key + corresponds to a queue name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-p</option></term> + <term><option>--persistent</option></term> + <listitem> + <para> + Use the persistent delivery mode. Without + this option, non-persistent delivery is used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-C</option></term> + <term><option>--content-type</option>=<replaceable class="parameter">MIME type</replaceable></term> + <listitem> + <para> + Specifies the content-type property for the + message. If omitted, the content-type + property is not set on the message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-E</option></term> + <term><option>--content-encoding</option>=<replaceable class="parameter">content coding</replaceable></term> + <listitem> + <para> + Specifies the content-encoding property for + the message. If omitted, the content-encoding + property is not set on the message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-b</option></term> + <term><option>--body</option>=<replaceable class="parameter">message body</replaceable></term> + <listitem> + <para> + Specifies the message body. If omitted, the + message body is read from standard input. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <variablelist> + <varlistentry> + <term>Send a short message, consisting of the word + <quote><literal>Hello</literal></quote> to the queue + <quote><systemitem + class="resource">myqueue</systemitem></quote> via the + default exchange:</term> + <listitem> + <screen><prompt>$ </prompt><userinput>amqp-publish -r myqueue -b Hello</userinput></screen> + </listitem> + </varlistentry> + + <varlistentry> + <term>Send some XML data from a file to the exchange + <quote><systemitem + class="resource">events</systemitem></quote>, with + persistent delivery mode, setting the content-type + property on the message to make the data format + explicit:</term> + <listitem> + <screen><prompt>$ </prompt><userinput>amqp-publish -e events -p -C text/xml <event.xml</userinput></screen> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See also</title> + <para> + <citerefentry><refentrytitle>librabbitmq-tools</refentrytitle><manvolnum>7</manvolnum></citerefentry> + describes connection-related options common to all the + RabbitMQ C Client tools. + </para> + </refsect1> +</refentry> |