diff options
| -rw-r--r-- | pullimap.1 | 87 |
1 files changed, 80 insertions, 7 deletions
@@ -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 |