X-Git-Url: https://git.distorted.org.uk/~mdw/qmail/blobdiff_plain/0a045fc157596a9521a5acff73297cc4a7c6c688..dd1ee02180d4b2379a72ae2840c41bf204a4a244:/addrcheck.c

diff --git a/addrcheck.c b/addrcheck.c
index 08d29b9..b463bd8 100644
--- a/addrcheck.c
+++ b/addrcheck.c
@@ -17,6 +17,23 @@
 
 #define STRALLOC_INIT { 0 }
 
+/* --- @probe@ --- *
+ *
+ * Arguments:	@int cdb@ = the CDB file descriptor
+ *		@int prefix@ = the prefix character (e.g., @'V'@)
+ *		@const char *key, int len@ = the key string and its length
+ *		@const char *suffix@ = a suffix to append to the key
+ *		@const char **kp@ = where to put the full key string
+ *		@uint32 *dlen@ = where to put the answer's length
+ *
+ * Returns:	Zero if the lookup failed, @+1@ on success, or @-1@ for an
+ *		error.
+ *
+ * Use:		Probes a CDB file.  The key looked up is the character
+ *		@prefix@ followed by the first @len@ bytes of @key@, followed
+ *		by @suffix@ (if non-null).
+ */
+
 static int probe(int cdb, int prefix, const char *key, int len,
 		 const char *suffix, const char **kp, uint32 *dlen)
 {
@@ -57,6 +74,24 @@ static int probe(int cdb, int prefix, const char *key, int len,
   return (rc);
 }
 
+/* --- @localprobe@ --- *
+ *
+ * Arguments:	@int cdb@ = the CDB file descriptor
+ *		@const char *sender@ = the envelope-sender address
+ *		@const char *key, int len@ = the (possibly defaulted) mailbox
+ *			name to look up
+ *		@const char *suffix@ = a suffix to append to the key (e.g.,
+ *			@"-default"@)
+ *		@const char *tail@ = the tail of the local address matching
+ *			any defaulted extension part
+ *		@int *rc@ = where to put the answer
+ *
+ * Returns:	Positive if found, zero if not found, negative on error.
+ *
+ * Use:		Looks up a local-part in the database.  This may involve
+ *		invoking a Userv service for the recipient's owner.
+ */
+
 static int localprobe(int cdb, const char *sender,
 		      const char *key, int len,
 		      const char *suffix, const char *tail, int *rc)
@@ -121,6 +156,22 @@ static int localprobe(int cdb, const char *sender,
   return (1);
 }
 
+/* --- @local@ --- *
+ *
+ * Arguments:	@int cdb@ = file descriptor for the CDB
+ *		@const char *l@ = pointer to local-part to look up
+ *		@int len@ = length of the local-part
+ *		@const char *sender@ = envelope sender address
+ *		@int *rc@ = where to put the answer
+ *
+ * Returns:	Positive if answered, zero if lookup failed, negative on
+ *		error.
+ *
+ * Use:		Finds out whether @l@ is a valid local-part for a non-virtual
+ *		mailbox name.  Handles defaulting of extension addresses and
+ *		suchlike.
+ */
+
 static int local(int cdb, const char *l, int len,
 		 const char *sender, int *rc)
 {
@@ -153,6 +204,23 @@ done:
   return (err);
 }
 
+/* --- @virt@ --- *
+ *
+ * Arguments:	@int cdb@ = file descriptor for CDB
+ *		@const char *u@ = the local-part of the recipient mailbox
+ *		@int ulen@ = length of the local-part
+ *		@const char *addr@ = the virtual domain to look up
+ *		@int alen@ = length of the virtual domain
+ *		@const char *sender@ = the envelope sender address
+ *		@int *rc@ = where to put the answer
+ *
+ * Returns:	Positive if found, zero if not found, negative on error.
+ *
+ * Use:		Looks up the address as a virtual domain.  If found, the
+ *		local-part is appended to the local mailbox handling the
+ *		virtual domain and passed to @local@.
+ */
+
 static int virt(int cdb, const char *u, int ulen,
 		const char *addr, int alen, const char *sender, int *rc)
 {
@@ -172,6 +240,20 @@ static int virt(int cdb, const char *u, int ulen,
   return (1);
 }
 
+/* --- @addrcheck@ --- *
+ *
+ * Arguments:	@int cdb@ = file descriptor for CDB to look things up in
+ *		@const char *addr@ = the (full) recipient mailbox to look up
+ *		@const char *sender@ = the (full) envelope sender address
+ *		@int *rc@ = where to put the answer.
+ *
+ * Returns:	Nonnegative on success, or @-1@ on failure.
+ *
+ * Use:		Determines whether @addr@ is a valid mailbox on this system,
+ *		by examining the given CDB file.  On exit, @*rc@ is set to
+ *		@'+'@ if the mailbox is valid, or @'-'@ if not.
+ */
+
 int addrcheck(int cdb, const char *addr, const char *sender, int *rc)
 {
   int at, len, dot;