Debian Codegraph @

upstream/debian-unstable/man1/lockmail.maildrop.1

raw
1 '\" t
2 .\"<!-- Copyright 2002-2007 Double Precision, Inc. See COPYING for -->
3 .\"<!-- distribution information. -->
4 .\" Title: lockmail
5 .\" Author: Sam Varshavchik
6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
7 .\" Date: 10/09/2025
8 .\" Manual: Double Precision, Inc.
9 .\" Source: Courier Mail Server
10 .\" Language: English
11 .\"
12 .TH "LOCKMAIL" "1" "10/09/2025" "Courier Mail Server" "Double Precision, Inc\&."
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 .nr an-no-space-flag 1
97 .nr an-break-flag 1
98 .br
99 .ps +1
100 \fBNote\fR
101 .ps -1
102 .br
103 .PP
104 A race condition exists where a
105 C\-Client
106 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
107 C\-Client
108 library does not appear to ever clear out the lock file\&.
109 .PP
110 \fBlockmail\fR
111 attempts to resolve this race condition by deleting zero\-length lock files that are at least five minutes old\&.
112 .sp .5v
113 .RE
114 .SS "dot\-locks"
115 .PP
116 \fBlockmail\fR
117 also creates, and honors dot\-lock files\&. Dot\-lock files are first created as temporary files, then linked to
118 \fIlockfile\fR\&.lock\&. The link operation fails if the dot\-lock file already exists\&.
119 \fBlockmail\fR
120 uses an enhanced method of dot\-locking, where its process ID, and the name of the server where
121 \fBlockmail\fR
122 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
123 \fBlockmail\fR
124 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\&.
125 .if n \{\
126 .sp
127 .\}
128 .RS 4
129 .nr an-no-space-flag 1
130 .nr an-break-flag 1
131 .br
132 .ps +1
133 \fBNote\fR
134 .ps -1
135 .br
136 .PP
137 A failure to create a dot\-lock file is silently ignored if the reason for the failure is because
138 \fBlockmail\fR
139 does not have the write permission in the dot\-lock file\*(Aqs directory\&. The incoming mail spool directory (usually
140 /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
141 \fBlockmail\fR
142 will be content with using file\-locking only\&.
143 .sp .5v
144 .RE
145 .SS "File locks"
146 .PP
147 The final locking mechanism
148 \fBlockmail\fR
149 uses is the operating system\*(Aqs file locking facility\&. If
150 \fBlockmail\fR
151 fails to obtain all three locks,
152 \fBlockmail\fR
153 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
154 \fBlockmail\fR
155 still fails to obtain all required locks in the amount of time specified by the
156 \fB\-t\fR
157 option (or its default value),
158 \fBlockmail\fR
159 will terminate with the
160 EX_TEMPFAIL
161 exit code\&.
162 .PP
163 \fBlockmail\fR
164 runs
165 \fIprogram\fR
166 after obtaining the last file lock, waits until
167 \fIprogram\fR
168 terminates, and releases all locks\&.
169 \fIprogram\fR
170 must terminate before any of the locks obtained by
171 \fBlockmail\fR
172 expire, and are considered stale\&.
173 \fBlockmail\fR
174 will then terminate with the same exit code as
175 \fIprogram\fR\&.
176 .SH "EXIT STATUS"
177 .PP
178 \fBlockmail\fR
179 terminates with the same exit status as
180 \fIprogram\fR
181 \fBlockmail\fR
182 terminates with the
183 EX_TEMPFAIL
184 exit status if it was unable to obtain a lock, or if
185 \fIprogram\fR
186 was killed by a signal\&.
187 .SH "SEE ALSO"
188 .PP
189 \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2,
190 \fBsendmail\fR(8)\&.
191 .SH "AUTHOR"
192 .PP
193 \fBSam Varshavchik\fR
194 .RS 4
195 Author
196 .RE
197 .SH "NOTES"
198 .IP " 1." 4
199 \fBmaildrop\fR(1)
200 .RS 4
201 \%http://www.courier-mta.org/maildrop.html
202 .RE