11.6 Printing the Queue

When sendmail is run under the name mailq, or when it is given the -bp command-line switch, it prints the contents of the queue and exits.

Before printing the queue's contents, sendmail prereads all the qf files in the queue and sorts the mail messages internally. This is done so that the queue's contents are displayed in the same order in which the messages will be processed during a queue run.

If there are no messages in the queue (no qf files), sendmail prints the following message and exits or, if there are multiple queues, goes on to the next queue:

/path is empty

Here, /path is the full pathname of the queue directory.

If the queue is not empty, sendmail prints the number of messages (number of qf files) in the queue:

/path (num requests)

The num is the number of queued messages (requests) in the queue directory. If this is more than the maximum number of messages that can be processed at one time (defined by the MaxQueueRunSize option (MaxQueueRunSize),^[9] sendmail prints:

^[9] Prior to V8.7 this was determined by defining QUEUESIZE in conf.h.

/path (num requests, only ## printed)

The ## is the value of the MaxQueueRunSize option.

Note that it can take several minutes to presort and print extremely full queues (queues with more than 10,000 messages in them). To see how many messages are queued, and to avoid the delay of a presort, you can add a small MaxQueueRunSize to your invocation of mailq:

% mailq -OMaxQueueRunSize=1

This will cause sendmail to swiftly print the number of queued messages, regardless of how many are queued.

After sendmail prints the number of messages in the queue, it prints an attractive heading such as the following:

----Q-ID---- --Size-- -----Q-Time----- ------------Sender/Recipient------------
dB928Xl04182      354 Fri Mar 15 08:32 your@your.domain
                                   george@wash.dc.gov
dB928RR04181*    1972 Fri Mar 15 08:45 your@your.domain
      8BITMIME   (Timed out waiting to connect to wash.dc.gov)
                                   jefferson@wash.dc.gov
dB928RR04192-      23 Fri Mar 15 09:32 your@your.domain
                 (Timed out waiting to connect to wash.dc.gov)
                                   jefferson@wash.dc.gov
                                   bob

The heading shows the information that is printed about each message in the queue. The items in that heading and their meanings are as follows:

Q-ID

The queue identifier for the message. This item can be followed by a character showing the item's status. An asterisk (* as in the second item in the example) means that the message is locked (an lf file was found, or the qf file is locked depending on the kind of locking your version of sendmail uses). An X means that the load average is currently too high to allow delivery of the message. A minus (- as in the third item in the example) means that the message is too young to be processed (based on the MinQueueAge option, MinQueueAge).

Size

The size in bytes of the df file. If there is no df file (because sendmail is currently receiving this message and hasn't created one yet), this item is absent. If the message has completed processing, this prints as:

(job completed)

If the qf file is empty, this prints as:

(no control file)

Q-Time

The date and time that the message was first placed into the queue. This is the T line (T line) in the qf file converted from an unsigned integer into a more understandable date and time.

Sender

The sender of the message as taken from the S line (S line) in the qf file. Only the first 45 characters of the sender address are printed. If there is a B line (B line) in the qf file (as the BITMIME in the second item in the example), sendmail prints that body-type (the -B switch in -B) on the line following the sender. If there is an M line (M line) in the qf file, sendmail prints the text of the error message in parentheses.

Recipient

After all of the above items have been printed, a list of the recipients (from each R line, R line, in the qf file) is printed in the order in which they are found. In the example there is one recipient for each of the first two items and two recipients for the last item.

See Section 11.8.2.3 for a way to limit the printed queue list to include only a subset of messages based on queue ID, sender, or recipient addresses.

11.6.1 Printing the Queue in Verbose Mode

The -v command-line switch can be used in combination with the -bp switch to cause sendmail to also print additional details about the queued messages. To begin, the usual heading shows a new item:

----Q-ID---- --Size-- -Priority- -----Q-Time----- ---------Sender/Recipient---------
dB928Xl04182     354     54320 Fri Mar 15 08:32 your@your.domain
                                  george@wash.dc.gov
dB928RR04181*   1972     39020 Fri Mar 15 08:45 your@your.domain
      8BITMIME   (Timed out waiting to connect to wash.dc.gov)
                                  jefferson@wash.dc.gov
dB928RR04192-     23     30001+Fri Mar 15 09:32 your@your.domain
                 (Timed out waiting to connect to wash.dc.gov)
                                  jefferson@wash.dc.gov
                               (---you---)
                                   bob

The Priority is the value from the P line (P line) in the qf file. Printing the queue does not change a message's priority, whereas processing the queue does. See the RecipientFactor option (RecipientFactor) for a description of how the priority is calculated.

Verbose mode also causes a + to print after the Priority (as in the third item in the example) if a warning message has been sent. See the Timeout.queuewarn option (Timeout) for a description of how messages time out.

If any R line is preceded by a controlling user (the C line in the qf file, C line), verbose mode causes that controlling user's name to be put in parentheses and prepended to the recipient name. The third item in the preceding example illustrates this.

Prior to V8.8 sendmail, the M line error messages were truncated to 60 characters. Beginning with V8.8, verbose mode causes the full, nontruncated text of the M line error to be printed.

11.6.2 Print the Number of Messages in the Queue

Beginning with V8.12 sendmail the -bP command-line switch can be used to print the number of messages in the queue or queues. This command-line switch relies on shared memory to gather its information, so it works only if sendmail is compiled with shared memory support. The SM_CONF_SHM compile-time macro determines whether shared memory support was included (see SM_CONF_SHM). If shared memory support is not included, use of this command-line switch will cause the following error to be printed:

Data unavailable without shared memory support

If shared memory support is compiled in, but there is a problem with it (possibly at the system level), the following error will print:

Data unavailable: shared memory not updated

Note that you will also get this error if the queue has not been processed at least once to initialize the data.

In addition to enabling shared memory using the SM_CONF_SHM m4 Build macro, you must also define a key to be used with that shared memory with the SharedMemoryKey option. To set this option in your configuration file, you could add a line such as the following to your mc configuration file:

define(`confSHARED_MEMORY_KEY',`13521')

If all goes well, the -bP command-line switch will produce output such as this:

/var/spool/mqueues/q.1/df: entries=34
/var/spool/mqueues/q.2/df: entries=51
               Total requests: 85

Here, 85 is the number of envelopes currently awaiting delivery in sendmail's queues. But note that some shared memory timeouts can lead to an inexact count. In this latter event the output looks like this:

Total requests: 85 (about)

If you lack shared memory support, and you are running pre-V8.12 sendmail, you can still summarize the number of messages in all queues with a simple substitute command:

% mailq -OMaxQueueRunSize=0