Commit | Line | Data |
---|---|---|
b0322a85 CE |
1 | '\" t |
2 | .\"<!-- Copyright 2002-2007 Double Precision, Inc. See COPYING for --> | |
3 | .\"<!-- distribution information. --> | |
4 | .\" Title: lockmail | |
5 | .\" Author: Sam Varshavchik | |
0e333c05 CE |
6 | .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> |
7 | .\" Date: 09/08/2017 | |
b0322a85 CE |
8 | .\" Manual: Double Precision, Inc. |
9 | .\" Source: Courier Mail Server | |
10 | .\" Language: English | |
11 | .\" | |
0e333c05 | 12 | .TH "LOCKMAIL" "1" "09/08/2017" "Courier Mail Server" "Double Precision, Inc\&." |
b0322a85 CE |
13 | .\" ----------------------------------------------------------------- |
14 | .\" * Define some portability stuff | |
15 | .\" ----------------------------------------------------------------- | |
16 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
17 | .\" http://bugs.debian.org/507673 | |
18 | .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html | |
19 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
20 | .ie \n(.g .ds Aq \(aq | |
21 | .el .ds Aq ' | |
22 | .\" ----------------------------------------------------------------- | |
23 | .\" * set default formatting | |
24 | .\" ----------------------------------------------------------------- | |
25 | .\" disable hyphenation | |
26 | .nh | |
27 | .\" disable justification (adjust text to left margin only) | |
28 | .ad l | |
29 | .\" ----------------------------------------------------------------- | |
30 | .\" * MAIN CONTENT STARTS HERE * | |
31 | .\" ----------------------------------------------------------------- | |
32 | .SH "NAME" | |
33 | lockmail \- create mail lock files | |
34 | .SH "SYNOPSIS" | |
35 | .HP \w'\fBlockmail\fR\ 'u | |
36 | \fBlockmail\fR [\-r] [\-t\ \fItimeout\fR] {\fIlockfile\fR} {\fIprogram\fR} [argument...] | |
37 | .SH "DESCRIPTION" | |
38 | .PP | |
39 | \fBlockmail\fR | |
40 | is a helper utility for working with mailbox files\&. Mailbox files must be locked to prevent other applications from modifying the mailbox at the same time\&. Different system use different locking conventions\&. | |
41 | \fBlockmail\fR | |
42 | uses two of the most common locking mechanisms in use, which should work reliably on most systems\&. | |
43 | .PP | |
44 | \fIlockfile\fR | |
45 | is the pathname to an existing mailbox file\&. By default, | |
46 | \fBlockmail\fR | |
47 | tries to lock the mailbox every five seconds (if the mailbox is already locked), and will give up after three minutes\&. After the mailbox is successfully locked, | |
48 | \fBlockmail\fR | |
49 | runs | |
50 | \fIprogram\fR | |
51 | as a child process, with any optional | |
52 | \fIargument\fRs\&. When | |
53 | \fIprogram\fR | |
54 | terminates, | |
55 | \fBlockmail\fR | |
56 | removes the mailbox lock, and terminates itself\&. | |
57 | .SH "OPTIONS" | |
58 | .PP | |
59 | \-r | |
60 | .RS 4 | |
61 | If a regular lock fails, try a read\-only lock\&. Use this option to lock mailbox files in a read\-only directory\&. | |
62 | .RE | |
63 | .PP | |
64 | \-t \fItimeout\fR | |
65 | .RS 4 | |
66 | If the lock attempt fails, try again for up to | |
67 | \fItimeout\fR | |
68 | seconds\&. The actual timeout is rounded up to the next five second interval (a lock attempt is tried every five seconds)\&. | |
69 | .RE | |
70 | .SH "DESCRIPTION" | |
71 | .PP | |
72 | This section briefly describes the locking mechanism used by | |
73 | \fBlockmail\fR\&. | |
74 | \fBlockmail\fR | |
75 | uses three different locking conventions in order to maximize compatibility with other mail software: C\-Client folder locks, dot\-locks, and file locks\&. | |
76 | .SS "C\-Client folder locks" | |
77 | .PP | |
78 | Mail software based on the | |
79 | C\-Client | |
80 | library creates lock files named | |
81 | /tmp/\&.\fIdddddd\fR\&.\fIiiiiii\fR\&. Here, | |
82 | \fIdddddd\fR | |
83 | and | |
84 | \fIiiiiii\fR | |
85 | are the device number and the inode number of the mailbox file (the | |
86 | \fIst_dev\fR | |
87 | and | |
88 | \fIst_ino\fR | |
89 | fields in the inode), in hexadecimal\&. If the process ID saved in the C\-Client folder lock file is not valid, | |
90 | \fBlockmail\fR | |
91 | concludes that it\*(Aqs a stale lock file, and will remove it\&. | |
92 | .if n \{\ | |
93 | .sp | |
94 | .\} | |
95 | .RS 4 | |
96 | .it 1 an-trap | |
97 | .nr an-no-space-flag 1 | |
98 | .nr an-break-flag 1 | |
99 | .br | |
100 | .ps +1 | |
101 | \fBNote\fR | |
102 | .ps -1 | |
103 | .br | |
104 | .PP | |
105 | A race condition exists where a | |
106 | C\-Client | |
107 | process is killed after it creates a lock file, but before saving its process ID in the lock file\&. The race window is very small, but it exists\&. The | |
108 | C\-Client | |
109 | library does not appear to ever clear out the lock file\&. | |
110 | .PP | |
111 | \fBlockmail\fR | |
112 | attempts to resolve this race condition by deleting zero\-length lock files that are at least five minutes old\&. | |
113 | .sp .5v | |
114 | .RE | |
115 | .SS "dot\-locks" | |
116 | .PP | |
117 | \fBlockmail\fR | |
118 | also creates, and honors dot\-lock files\&. Dot\-lock files are first created as temporary files, then linked to | |
119 | \fIlockfile\fR\&.lock\&. The link operation fails if the dot\-lock file already exists\&. | |
120 | \fBlockmail\fR | |
121 | uses an enhanced method of dot\-locking, where its process ID, and the name of the server where | |
122 | \fBlockmail\fR | |
123 | is running is also saved in its dot\-lock file\&. If the operation fails due to an existing dot\-lock file that was created by another | |
124 | \fBlockmail\fR | |
125 | process on the same server, and the process ID no longer exists, this stale dot\-lock file is removed immediately\&. In all other situations a dot\-lock file older than five minutes is considered stale, and removed\&. | |
126 | .if n \{\ | |
127 | .sp | |
128 | .\} | |
129 | .RS 4 | |
130 | .it 1 an-trap | |
131 | .nr an-no-space-flag 1 | |
132 | .nr an-break-flag 1 | |
133 | .br | |
134 | .ps +1 | |
135 | \fBNote\fR | |
136 | .ps -1 | |
137 | .br | |
138 | .PP | |
139 | A failure to create a dot\-lock file is silently ignored if the reason for the failure is because | |
140 | \fBlockmail\fR | |
141 | does not have the write permission in the dot\-lock file\*(Aqs directory\&. The incoming mail spool directory (usually | |
142 | /var/mail) typically does not have global write permissions, so the attempt to create the dot\-lock file in the spool directory will fail, and | |
143 | \fBlockmail\fR | |
144 | will be content with using file\-locking only\&. | |
145 | .sp .5v | |
146 | .RE | |
147 | .SS "File locks" | |
148 | .PP | |
149 | The final locking mechanism | |
150 | \fBlockmail\fR | |
151 | uses is the operating system\*(Aqs file locking facility\&. If | |
152 | \fBlockmail\fR | |
153 | fails to obtain all three locks, | |
154 | \fBlockmail\fR | |
155 | will sleep for five seconds and try again\&. The only exception is a failure to create a dot\-lock because of no write access to the dot\-lock file\*(Aqs directory, which is ignored\&. If | |
156 | \fBlockmail\fR | |
157 | still fails to obtain all required locks in the amount of time specified by the | |
158 | \fB\-t\fR | |
159 | option (or its default value), | |
160 | \fBlockmail\fR | |
161 | will terminate with the | |
162 | EX_TEMPFAIL | |
163 | exit code\&. | |
164 | .PP | |
165 | \fBlockmail\fR | |
166 | runs | |
167 | \fIprogram\fR | |
168 | after obtaining the last file lock, waits until | |
169 | \fIprogram\fR | |
170 | terminates, and releases all locks\&. | |
171 | \fIprogram\fR | |
172 | must terminate before any of the locks obtained by | |
173 | \fBlockmail\fR | |
174 | expire, and are considered stale\&. | |
175 | \fBlockmail\fR | |
176 | will then terminate with the same exit code as | |
177 | \fIprogram\fR\&. | |
178 | .SH "EXIT STATUS" | |
179 | .PP | |
180 | \fBlockmail\fR | |
181 | terminates with the same exit status as | |
0e333c05 CE |
182 | \fIprogram\fR |
183 | \fBlockmail\fR | |
b0322a85 CE |
184 | terminates with the |
185 | EX_TEMPFAIL | |
186 | exit status if it was unable to obtain a lock, or if | |
187 | \fIprogram\fR | |
188 | was killed by a signal\&. | |
189 | .SH "SEE ALSO" | |
190 | .PP | |
191 | \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2, | |
192 | \fBsendmail\fR(8)\&. | |
193 | .SH "AUTHOR" | |
194 | .PP | |
195 | \fBSam Varshavchik\fR | |
196 | .RS 4 | |
197 | Author | |
198 | .RE | |
199 | .SH "NOTES" | |
200 | .IP " 1." 4 | |
201 | \fBmaildrop\fR(1) | |
202 | .RS 4 | |
0e333c05 | 203 | \%http://www.courier-mta.org/maildrop.html |
b0322a85 | 204 | .RE |