usr/src/man/man3mail/maillock.3mail

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH MAILLOCK 3MAIL "Mar 29, 1999"
   7 .SH NAME
   8 maillock, mailunlock, touchlock \- functions to manage lockfile(s) for user's
   9 mailbox
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lmail\fR [ \fIlibrary\fR ... ]
  14 #include <maillock.h>
  15
  16
  17
  18 \fBint\fR \fBmaillock\fR(\fBconst char *\fR\fIuser\fR, \fBint\fR \fIretrycnt\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBmailunlock\fR(\fBvoid\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBtouchlock\fR(\fBvoid\fR);
  29 .fi
  30
  31 .SH DESCRIPTION
  32 .sp
  33 .LP
  34 The \fBmaillock()\fR function attempts to create a lockfile for the user's
  35 mailfile. If a lockfile already exists, and it has not been modified in the
  36 last 5 minutes, \fBmaillock()\fR will remove the lockfile and set its own
  37 lockfile.
  38 .sp
  39 .LP
  40 It is crucial that programs locking mail files refresh their locks  at least
  41 every three minutes to maintain the lock. Refresh the lockfile by calling the
  42 \fBtouchlock()\fR function with no arguments.
  43 .sp
  44 .LP
  45 The algorithm used to determine the age of the lockfile takes into account
  46 clock drift between machines using a network file system. A zero is written
  47 into the lockfile so that the lock will  be respected by systems running the
  48 standard version of System V.
  49 .sp
  50 .LP
  51 If the lockfile has been modified in the last 5 minutes  the process will sleep
  52 until the lock is available. The sleep algorithm is to sleep for 5 seconds
  53 times the attempt number. That is, the first sleep will be for 5 seconds, the
  54 next sleep will be for 10 seconds, etc. until the number of attempts reaches
  55 \fIretrycnt\fR.
  56 .sp
  57 .LP
  58 When the lockfile is no longer needed, it should be removed by calling
  59 \fBmailunlock()\fR.
  60 .sp
  61 .LP
  62 The \fIuser\fR argument is the login name of the user for whose mailbox the
  63 lockfile will be created. \fBmaillock()\fR assumes that user's mailfiles are in
  64 the ``standard'' place as defined in  <\fBmaillock.h\fR>.
  65 .SH RETURN VALUES
  66 .sp
  67 .LP
  68 Upon successful completion, .\fBmaillock()\fR returns \fB0\fR. Otherwise it
  69 returns \fB\(mi1\fR\&.
  70 .SH FILES
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fB/var/mail/*\fR\fR
  75 .ad
  76 .RS 20n
  77 user mailbox files
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fB/var/mail/*.lock\fR\fR
  84 .ad
  85 .RS 20n
  86 user mailbox lockfiles
  87 .RE
  88
  89 .SH ATTRIBUTES
  90 .sp
  91 .LP
  92 See \fBattributes\fR(5) for descriptions of the following attributes:
  93 .sp
  94
  95 .sp
  96 .TS
  97 box;
  98 c | c
  99 l | l .
 100 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 101 _
 102 MT-Level        Unsafe
 103 .TE
 104
 105 .SH SEE ALSO
 106 .sp
 107 .LP
 108 \fBlibmail\fR(3LIB),\fBattributes\fR(5)
 109 .SH NOTES
 110 .sp
 111 .LP
 112 The \fBmailunlock()\fR function will only remove the lockfile created from the
 113 most previous call to \fBmaillock()\fR. Calling \fBmaillock()\fR for different
 114 users without intervening calls to \fBmailunlock()\fR will cause the initially
 115 created lockfile(s) to remain, potentially blocking subsequent message delivery
 116 until the current process finally terminates.