summaryrefslogtreecommitdiff
path: root/tools/doc/consume.xml
blob: 16d61ad8720dbe76b0de92bdce3637019ca7f3ad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
<?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 &lt;<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>&gt;</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.
        </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.
                    </para>
                        
                    <para>
                        If the <option>--queue</option> option is
                        omitted, the AMQP server will assign a unique
                        name to the queue, and that server-assigned
                        name will be dixsplayed on stderr; this case
                        implies that an exclusive queue should be
                        declared.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><option>-e</option></term>
                <term><option>--exchange</option>=<replaceable class="parameter">exchange name</replaceable></term>
                <listitem>
                    <para>
                        Specifies that an exclusive queue should
                        be declared, and bound to the given exchange.
                        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>-r</option></term>
                <term><option>--routing-key</option>=<replaceable class="parameter">routing key</replaceable></term>
                <listitem>
                    <para>
                        The routing key for binding.  If omitted, an
                        empty routing key is assumed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><option>-d</option></term>
                <term><option>--declare</option></term>
                <listitem>
                    <para>
                        Forces an exclusive queue to be declared,
                        even when it otherwise would not.  That is,
                        when a queue name is specified with the
                        <option>--queue</option> option, but no
                        binding to an exchange is requested with the
                        <option>--exchange</option> option.
                    </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 an existing 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 new exclusive 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>