5.18 Mailbox Functions

A set of functions is provided for accessing mailboxes and messages within them. In this subsection we describe the functions for accessing mailboxes.

A mailbox is opened using mailbox_open function:

Built-in Function: number mailbox_open (string url [, string mode, string perms])

Open a mailbox identified by url. Return a mailbox descriptor: a unique numeric identifier that can subsequently be used to access this mailbox.

The optional mode argument specifies the access mode for the mailbox. Its valid values are:

Value	Meaning
r	Open mailbox for reading. This is the default.
w	Open mailbox for writing. If the mailbox does not exist, it is created.
rw	Open mailbox for reading and writing. If the mailbox does not exist, it is created.
wr	Same as ‘rw’.
w+	Open mailbox for reading and writing. If the mailbox does not exist, it is created.
a	Open mailbox for appending messages to it. If the mailbox does not exist, an exception is signalled.
a+	Open mailbox for appending messages to it. If the mailbox does not exist, it is created.

The optional perms argument specifies the permissions to use in case a new file (or files) is created. It is a comma-separated list of:

[go](+|=)[wr]+

The initial letter controls which users’ access is to be set: users in the file’s group (‘g’) or other users not in the file’s group (‘o’). The following character controls whether the permissions are added to the default ones (‘+’) or applied instead of them (‘=’). The remaining letters specify the permissions: ‘r’ for read access and ‘w’ for write access. For example:

g=rw,o+r

The number of mailbox descriptors available for simultaneous opening is 64. This value can be changed using the max-open-mailboxes runtime configuration statement (see max-open-mailboxes).

Built-in Function: number mailbox_messages_count (number nmbx)

Return the number of messages in mailbox. The argument nmbx is a valid mailbox descriptor as returned by a previous call to mailbox_open.

Built-in Function: number mailbox_get_message (number mbx, number n)

Retrieve nth message from the mailbox identified by descriptor mbx. On success, the function returns a message descriptor, an integer number that can subsequently be used to access that message (see Message functions). On error, an exception is raised.

Messages in a mailbox are numbered starting from 1.

Built-in Function: void mailbox_close (number nmbx)

Close a mailbox previously opened by mailbox_open.

Built-in Function: void mailbox_append_message (number nmbx, number nmsg)

Append message nmsg to mailbox nmbx. The message descriptor nsmg must be obtained from a previous call to mailbox_get_message or current_message (see current_message).