* doc/mbox.texi: Starts to document the concrete Unix mbox

	API.
	* doc/pop3.texi: Typos.
	* mailbox/mbx_mh.c: Initialised variables. Typecast to void
	expunge since it is never used.
	* mail/delete.c : Typo.

 2001-09-16  Alain Magloire
 
+	* doc/mbox.texi: Starts to document the concrete Unix mbox
+	API.
+	* doc/pop3.texi: Typos.
+	* mailbox/mbx_mh.c: Initialised variables. Typecast to void
+	expunge since it is never used.
+	* mail/delete.c : Typo.
+
+2001-09-16  Alain Magloire
+
 	This is after a exchange with Dave Inglis and Sam Roberts.
 	Basically they recommand to drop the XX_release() functions
 	and only to keep XX_create (), XX_destroy ().  We have simple

@@ -4,4 +4,339 @@
 
 @end example
 
-Standard Unix Mailbox.  Not implemented.
+The most common mailbox format on UNIX platform is @emph{mbox}.  Mbox file
+is messages separated by the special format string.
+@example
+   From SP envelope-sender SP date [SP moreinfo]
+@end example
+
+@table @code
+@item "From "
+ is sometimes call the @emph{From_}.
+@item  evelope-sender
+ is a word with no space.
+@item date
+ has the same format as @code{asctime ()}
+@item moreinfo
+ are optional values that are seldom used.
+@end table
+
+A @var{mbox_t} is created, initialised and destroyed by @code{mbox_create ()}
+and @code{mbox_destroy ()}. When opening, @code{mbox_open ()} will do a quick
+check to see if the format is a valid format or an empty file. The scanning
+of the mailbox is done by @code{mbox_scan ()}.
+The function, @code{mbox_scan ()}, takes callback functions called during the
+scanning to provide information. The scanning will cache some of the headers
+fields for speed.  Closing the mailbox, @code{mbox_close ()} will free
+any ressources like, headers cache, locks etc ... All the messages with
+attributes marked deleted will only be removed on @code{mbox_expunge ()}.
+If only the attributes need to be save but the messages not removed, this
+can be done by @code{mbox_save_attributes ()}.  New messages are added with
+@code{mbox_append ()}.  Attributes are saved in the @emph{Status:} header
+field, Read is 'R', Seen is 'O', Deleted is 'd' and Reply is 'r'.
+
+@subsubsection Initialisation
+@cindex Mbox Initialisation
+
+@deftypefun int mbox_create (mbox_t *@var{mbox})
+
+Allocate and initialize a @var{mbox} handle.
+
+@table @code
+@item MU_ERROR_NO_MEMORY
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun void mbox_destroy (mbox_t @var{mbox})
+
+When a POP3 session is finished, the structure must be @code{free ()}'ed to
+reclaim memory.
+@end deftypefun
+
+@subsubsection Carrier
+@cindex Mbox channel
+
+@deftypefun int mbox_set_carrier (mbox_t, stream_t @var{carrier});
+
+Another type of stream can be provided to work on, the @var{carrier}
+is set in the @var{mbox_t} handle.  Any  previous @var{carrier} stream in
+the handle, will be close and release.  Since the parsing code
+maintain only the offsets off the message the @var{carrier} stream must be
+seekable.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_get_carrier (mbox_t, stream_t *@var{carrier});
+
+Return the @var{mbox_t} carrier.  If none was set, a new file stream will be
+created.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_open (mbox_t, const char *@var{filename}, int @var{flags})
+
+Open carrier stream with @var{filename} and @var{flags}.  The stream will be
+quickly examine to see if it is a mbox format.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@item MU_ERROR_NO_ENTRY
+@item MU_ERROR_NO_ACCESS
+@item MU_ERROR_NOT_SUPPORTED
+@end table
+@end deftypefun
+
+@deftypefun int mbox_close (mbox_t)
+
+Close the carrier stream and ressources particular to the mailbox.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_uidnext (mbox_t, unsigned long *@var{uidnext})
+
+Return the uidnext, if the @var{mbox_t} was not scan @code{mbox_scan ()}
+is called first.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item same as @code{mbox_scan ()}
+@end table
+@end deftypefun
+
+@deftypefun int mbox_uidvalidity (mbox_t, unsigned long *@var{uidvalidity})
+
+Return the uidvalidity, if the @var{mbox_t} was not scan @code{mbox_scan ()}
+is called first.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item same as @code{mbox_scan ()}
+@end table
+@end deftypefun
+
+@deftypefun int mbox_get_attribute (mbox_t, unsigned int @var{msgno}, attribute_t *@var{attribute})
+
+Return an @var{attribute} to indicate the status of message number @var{msgno}.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_get_separator (mbox_t, unsigned int @var{msgno}, char **@var{sep})
+
+Return an allocated string in @var{sep} containing the value "From " separating
+each message in Unix mbox format. The string should be @code{free ()}ed by
+the caller.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_separator (mbox_t, unsigned int @var{msgno}, const char *@var{sep})
+
+The variable @var{sep} should contain a valid "From " separtor that will be use
+when the expunging.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_get_hstream (mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})
+
+Return a @var{stream} to read the header of message @var{msgno}. The
+@var{stream} should be destroy after usage.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_hstream (mbox_t, unsigned int @var{msgno}, stream_t @var{stream})
+
+Use @var{stream} when expunging for message @var{msgno}.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_hsize (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
+
+Return the @var{size} of message @var{msgno}.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_hlines (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
+
+Return the number of @var{lines} of message @var{msgno}.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_get_bstream (mbox_t, unsigned int @var{msgno}, stream_t *@var{stream})
+
+Return a @var{stream} to read the body of message @var{msgno}. The
+@var{stream} should be destroy after usage.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_bstream (mbox_t, unsigned int @var{msgno}, stream_t @var{stream})
+
+Use @var{stream} when expunging for message @var{msgno}.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_bsize (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
+
+Return the @var{size} of message @var{msgno}.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_blines (mbox_t, unsigned int @var{msgno}, unsigned int *@var{size})
+
+Return the number of @var{lines} of message @var{msgno}.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_get_size (mbox_t, unsigned int *@var{size})
+
+Return the @var{size} of mailbox.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_save (mbox_t)
+
+Save the changes to the messages back to the mailbox, but do not
+remove messages mark for deletion in the process.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_mak_deleted (mbox_t, unsigned int @var{msgno})
+
+Mark @var{msgno} for deletion.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_unmak_deleted (mbox_t, unsigned int @var{msgno})
+
+Unmark @var{msgno} if it was marked for deletion.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_expunge (mbox_t)
+
+Save the changes to the mailbox and in the process remove all messages
+marked for deletion.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_append (mbox_t, const char *@var{sep}, stream_t @var{stream})
+
+Append to the mailbox an rfc822 message represented by @var{stream}.
+The variable @var{sep} should contain a valid "From " separator or
+NULL to get the default.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_append_hb (mbox_t, const char *@var{sep}, stream_t @var{hstream}, stream_t @var{bstream})
+
+Append to the mailbox an rfc822 message represented by a header, @var{hstream},
+and a body, @var{bstream}.  The variable @var{sep} should contain a valid
+"From " separator or NULL to get the default.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_scan (mbox_t, unsigned int start, unsigned int *@var{count})
+
+Start scanning the mailbox for new messages.  The variable @var{start} can be
+a message number starting point.  The result of the scanning will be in
+@var{count}.  The scanning will trigger the @code{mbox_newmsg_cb()} callback
+for each new message and @code{mbox_progress_cb ()} at different interval
+to notify progression.  The return values of the those callback should be
+0 is different then 0 the scanning will be stop an the function returns
+MU_ERROR_INTERRUPTED.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@item MU_ERROR_INTERRUPTED
+@item MU_ERROR_NO_MEMORY
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_progress_cb (mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})
+
+Set the callback function for progress.  The variable @var{arg} will be pass
+back in the callback as the second argument.
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun
+
+@deftypefun int mbox_set_newmsg_cb (mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})
+
+Set the callback function for new messages.  The variable @var{arg} will be
+pass back in the callback as the second argument.
+
+@table @code
+@item MU_ERROR_INVALID_PARAMETER
+@end table
+@end deftypefun

@@ -101,7 +101,7 @@ Allocate and initialize a @var{pop3} handle.
 @end table
 @end deftypefun
 
-@deftypefun int pop3_destroy (pop3_t @var{pop3})
+@deftypefun void pop3_destroy (pop3_t *@var{pop3})
 
 When a POP3 session is finished, the structure must be @code{free ()}'ed to
 reclaim memory.
@@ -130,8 +130,8 @@ until the return value is not MU_ERROR_TRY_AGAIN or MU_ERROR_IN_PROGRESS.
 
 @deftypefun int pop3_set_carrier (pop3_t, stream_t @var{carrier});
 
-A connection may have been opened elsewhere, in this case the @var{carrier}
-is set in the @code{pop3_t} handle.  Any  previous @var{carrier} stream in
+The type of stream use to contact as server will be set to @var{carrier}
+in the @var{pop3_t} handle.  Any  previous @var{carrier} stream in
 the handle, will be close and release.
 
 @table @code
@@ -141,7 +141,7 @@ the handle, will be close and release.
 
 @deftypefun int pop3_get_carrier (pop3_t, stream_t *@var{carrier});
 
-Return the @var{pop3_t} carrier.  If none was set, a new stream will be
+Return the @var{pop3_t} carrier.  If none was set, a new tcp stream will be
 created.
 
 @table @code

@@ -43,7 +43,7 @@ mail_delete (int argc, char **argv)
   else
     rc = mail_delete0 ();
 
-  /* Reajust the realcursor to no point to the deleted messages.  */
+  /* Readjust the realcursor to no point to the deleted messages.  */
   if (cursor == realcursor)
     {
       unsigned int here = realcursor;

@@ -479,7 +479,7 @@ static int
 _mh_message_save (struct _mh_data *mhd, struct _mh_message *mhm, int expunge)
 {
   stream_t stream = NULL;
-  char *name, *buf, *msg_name;
+  char *name, *buf = NULL, *msg_name;
   size_t n, off = 0;
   size_t bsize;
   FILE *fp;
@@ -488,6 +488,8 @@ _mh_message_save (struct _mh_data *mhd, struct _mh_message *mhm, int expunge)
   int status;
   attribute_t attr;
   body_t body;
+
+  (void)expunge;
   
   fp = _mh_tempfile (mhm->mhd, &name);
   if (!fp)