pullimap: add control flow details in the manpage.

1 files changed, 80 insertions, 7 deletions

diff --git a/pullimap.1 b/pullimap.1
index d4ef502..8f27d85 100644
--- a/pullimap.1
+++ b/pullimap.1
@@ -15,10 +15,11 @@ to a SMTP or LMTP transmission channel.
 It can also remove old messages after a configurable retention period.
 
 .PP
-A statefile is used to keep track of the mailbox's UIDVALIDITY and
-UIDNEXT values.  While \fBPullIMAP\fR is running, the statefile is also
-used to keep track of UIDs being delivered, which avoids duplicate
+A \fIstatefile\fR is used to keep track of the mailbox's UIDVALIDITY and
+UIDNEXT values.  While \fBPullIMAP\fR is running, the \fIstatefile\fR is
+also used to keep track of UIDs being delivered, which avoids duplicate
 deliveries if the process is interrupted.
+See the \fBCONTROL FLOW\fR section below.
 
 .SH OPTIONS
 .TP
@@ -38,10 +39,10 @@ default) to avoid being logged out for inactivity.
 
 .TP
 .B \fB\-\-no\-delivery
-Update the state file, but skip SMTP/LMTP delivery.  This is mostly
-useful for initializing the statefile when migrating to \fBPullIMAP\fR
-from another equivalent program such as \fIgetmail\fR(1) or
-\fIfetchmail\fR(1).
+Update the \fIstatefile\fR, but skip SMTP/LMTP delivery.  This is mostly
+useful for initializing the \fIstatefile\fR when migrating to
+\fBPullIMAP\fR from another equivalent program such as \fIgetmail\fR(1)
+or \fIfetchmail\fR(1).
 
 .TP
 .B \-q\fR, \fB\-\-quiet\fR
@@ -234,6 +235,78 @@ for more information.
 File containing trusted certificates to use during server certificate
 authentication if \(lq\fISSL_verify\fR=YES\(rq.
 
+.SH CONTROL FLOW
+\fBPullIMAP\fR opens the \fIstatefile\fR corresponding to a given
+configuration \fISECTION\fR with O_DSYNC to ensure that written data is
+flushed to the underlying hardware by the time \fIwrite\fR(2) returns.
+Moreover an exclusive lock is placed on the file descriptor immediately
+after opening to prevent multiple \fBpullimap\fR processes from
+accessing the \fIstatefile\fR concurrently.
+
+Each \fIstatefile\fR consists of a series of 32-bits big-endian
+integers.  Usually there are only two integers:
+the first is the \fImailbox\fR's UIDVALIDITY value, and the second is
+the \fImailbox\fR's last seen UIDNEXT value (\fBPullIMAP\fR then assumes
+that all messages with UID smaller than this UIDNEXT value have already
+been retrieved and delivered).
+The IMAP4rev1 specification [RFC 3501] does not guaranty that untagged
+FETCH responses are sent ordered by UID in response of an UID FETCH
+command.  Thus it would be unsafe for \fBPullIMAP\fR to update the
+UIDNEXT value in the \fIstatefile\fR while the UID FETCH command is
+progress.
+Instead, for each untagged FETCH response received while while the UID
+FETCH command is in progress, \fBPullIMAP\fR delivers the message BODY
+to the SMTP or LMTP server specified with \fIdeliver\-method\fR then
+appends the message UID to the \fIstatefile\fR.  When the UID FETCH
+command eventually terminates, \fBPullIMAP\fR updates the UIDNEXT value
+in the \fIstatefile\fR and truncate the file down to 8 bytes.
+Keeping track of message UIDs as they are received avoids duplicate in
+the even of a crash or session loss while the UID FETCH command is in
+progress.
+
+In more details, \fBPullIMAP\fR works as follows:
+
+.nr step 1 1
+.IP \n[step]. 4
+Issue an UID FETCH command to retrieve message ENVELOPE and BODY (and
+UID) with UID bigger or equal than the UIDNEXT value found in the
+\fIstatefile\fR.
+While the UID FETCH command is in progress, perform the following
+for each untagged FETCH response sent by the server:
+.RS
+.nr step 1 1
+.IP \n[step]. 4
+if no SMTP/LMTP transmission channel was opened, open one to the server
+specified with \fIdeliver\-method\fR and send an EHLO (or LHO) command
+with the domain given by \fIdeliver\-ehlo\fR;
+.IP \n+[step].
+perform a mail transaction (using SMTP pipelining [RFC 2920] if
+possible) to send the retrieved message BODY to the SMTP or LMTP
+session; and
+.IP \n+[step].
+append the message UID to the \fIstatefile\fR.
+.RE
+
+.IP \n-[step].
+If a SMTP/LMTP transmission channel was opened, send a QUIT command to
+close it gracefully.
+
+.IP \n+[step].
+Issue an UID STORE command to mark all retrieved messages (and stalled
+UIDs found in the \fIstatefile\fR after the UIDNEXT value) as \\Seen.
+
+.IP \n+[step].
+Update the \fIstatefile\fR with the new UIDNEXT value.
+
+.IP \n+[step].
+Truncate the \fIstatefile\fR down to 8 bytes (so that it contains only
+two 32-bits integers, respectively the \fImailbox\fR's UIDVALIDITY and
+UIDNEXT values).
+
+.IP \n+[step].
+If \fB\-\-idle\fR was set, issue an IDLE command; stop idling and go
+back to step 1. whenever a new message is received.
+
 .SH AUTHOR
 Written by Guilhem Moulin
 .MT guilhem@fripost.org