https://mailutils.org/usqay/api.php?action=feedcontributions&user=Gray&feedformat=atomMailutils - User contributions [en]2024-03-29T13:23:43ZUser contributionsMediaWiki 1.35.13https://mailutils.org/usqay/index.php?title=Main_Page&diff=541Main Page2024-01-06T14:48:55Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [https://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?h=release-3.17 version 3.17] is released on Jan 6, 2024. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.17.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=540Main Page2024-01-06T14:48:32Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [https://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?h=release-3.17 version 3.16] is released on Jan 6, 2024. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.17.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Struct_mu_timezone&diff=539Struct mu timezone2023-10-16T13:35:58Z<p>Gray: </p>
<hr />
<div>{{DISPLAYTITLE:struct mu_timezone}}<br />
The structure <tt>mu_timezone</tt> keeps time zone information. It is defined in <tt>mailutils/datetime.h</tt> as follows:<br />
<br />
<syntaxhighlight lang="C"><br />
struct mu_timezone<br />
{<br />
int utc_offset;<br />
const char *tz_name;<br />
};<br />
</syntaxhighlight><br />
<br />
Its members are:<br />
<br />
;tc_offset<br />
:Seconds east of UTC.<br />
;tz_name<br />
:Nickname for this timezone, if known. NULL otherwise. It is always considered to be a pointer to static string, so should never be freed.<br />
<br />
[[Category:Date/Time Functions]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Libmu_dbm&diff=538Libmu dbm2023-10-16T13:33:44Z<p>Gray: </p>
<hr />
<div>{{DISPLAYTITLE:libmu_dbm}}<br />
<br />
The library <tt>libmu_dbm</tt> provides a uniform and consistent interface to various <tt>DBM</tt>-like database managers. Presently (as of version 2.99.99), the following backend libraries are supported:<br />
<br />
* [http://www.gnu.org/software/gdbm GDBM]<br />
* [http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html Berkeley DB] (BDB)<br />
* Traditional [http://en.wikipedia.org/wiki/Ndbm NDBM]<br />
* [http://fallabs.com/tokyocabinet/ Tokyo Cabinet]<br />
* [http://fallabs.com/kyotocabinet/ Kyoto Cabinet]<br />
<br />
== Header Files and Libraries ==<br />
<br />
The data types and function prototypes of <tt>libmu_dbm</tt> are declared in <tt>mailutils/dbm.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/dbm.h</ref>. Internal interfaces, which are of interest for implementors of new backends, are declared in <tt>mailutils/sys/dbm.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/sys/dbm.h</ref>.<br />
<br />
File loader arguments for linking programs with <tt>libmu_dbm</tt> can be obtained running:<br />
<br />
mu ldflags dbm<br />
<br />
== Data Types ==<br />
<br />
A ''database file'' is represented by the <tt>mu_dbm_file_t</tt> type. It is an opaque type, declared as<br />
<br />
<syntaxhighlight lang="C"><br />
typedef struct _mu_dbm_file *mu_dbm_file_t;<br />
</syntaxhighlight><br />
<br />
A ''datum'' is a piece of information stored in the database. It is declared as:<br />
<br />
<syntaxhighlight lang="C"><br />
struct mu_dbm_datum<br />
{<br />
char *mu_dptr; /* Data pointer */<br />
size_t mu_dsize; /* Data size */<br />
void *mu_data; /* Implementation-dependent data */<br />
struct mu_dbm_impl *mu_sys; /* Pointer to implementation */<br />
};<br />
</syntaxhighlight><br />
<br />
Of all its fields, only <tt>mu_dptr</tt> and <tt>mu_dsize</tt> are of interest for application developers. The <tt>mu_dptr</tt> points to the actual data and <tt>mu_dsize</tt> keeps the number of bytes pointed to by <tt>mu_dptr</tt>.<br />
<br />
When initializing an object of <tt>struct mu_dbm_datum</tt> type it is important to fill all the rest of its fields with zeros. The usual initialization sequence is therefore:<br />
<br />
<syntaxhighlight lang="C"><br />
struct mu_dbm_datum key;<br />
<br />
memset (&key, 0, sizeof key);<br />
key.mu_dptr = data;<br />
key.mu_dsize = size;<br />
</syntaxhighlight><br />
<br />
== Global Variables ==<br />
<syntaxhighlight lang="C"><br />
mu_url_t mu_dbm_hint;<br />
</syntaxhighlight><br />
<br />
This variable keeps an [[URL hint]] which is used to supply missing URL parts for <tt>mu_dbm_create_from_url</tt> and <tt>mu_dbm_create</tt> calls (see next section). By default it contains only a scheme part pointing to the first available '''DBM''' implementation.<br />
<br />
This variable is <tt>NULL</tt> before any of the following functions is called: [[#mu_dbm_init|<tt>mu_dbm_init</tt>]], <tt>mu_dbm_get_hint</tt>, [[#mu_dbm_register|<tt>mu_dbm_register</tt>]], [[#mu_dbm_impl_iterator|<tt>mu_dbm_impl_iterator</tt>]], [[#Creating a Database Object|<tt>mu_dbm_create_from_url</tt>]] or [[#Creating a Database Object|<tt>mu_dbm_create</tt>]]. <br />
<br />
<div id="mu_dbm_get_hint"></div><br />
Therefore it is not recommended to use this variable directly. The preferred way is to use the the <tt>mu_dbm_get_hint</tt> function instead:<br />
<br />
<syntaxhighlight lang="C"><br />
mu_url_t mu_dbm_get_hint (void);<br />
</syntaxhighlight><br />
<br />
This function makes sure the variable is initialized before returning it.<br />
<br />
== Creating a Database Object ==<br />
<br />
A variable of type <tt>mu_dbm_file_t</tt> is created using the following functions:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_create_from_url (mu_url_t url, mu_dbm_file_t *db, int default_safety_flags);<br />
int mu_dbm_create (char *name, mu_dbm_file_t *db, int default_safety_flags);<br />
</syntaxhighlight><br />
<br />
The former function creates a database object from an URL supplied as its first argument. The latter one creates a database object from a file name or a [[Database URL|URL]] in string form. On success both functions store a pointer to the initialized <tt>struct _mu_dbm_file</tt> in the memory location pointed to by the '''db''' parameter and return 0. On error, they return a [[Error Code|Mailutils error code]] and do not touch '''db'''.<br />
<br />
The '''default_safety_flags''' argument specifies the default safety criteria to apply to the database unless explicitly stated in its [[Database_URL#param|URL parameters]]<br />
<br />
== Safety Checking ==<br />
<br />
The following function verifies whether the database file is [[File Safety Checks|safe to use]]:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_safety_check (mu_dbm_file_t db);<br />
</syntaxhighlight><br />
<br />
It returns 0 if the file is OK, or an [[File_Safety_Functions#MU_ERR_PERM|error code]] describing the problem otherwise.<br />
<br />
There are two ways to set safety criteria. First, they can be configured using the [[Database URL#param|URL parameters]] when calling <tt>mu_dbm_create_from_url</tt> or <tt>mu_dbm_create</tt>. Second, they can be set using the following functions:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_safety_set_flags (mu_dbm_file_t db, int flags);<br />
int mu_dbm_safety_set_owner (mu_dbm_file_t db, uid_t uid);<br />
</syntaxhighlight><br />
<br />
The <tt>mu_dbm_safety_set_flags</tt> functions defines the set of safety criteria for this file. The '''flags''' argument has the same meaning as the [[File_Safety_Functions#MU_FILE_SAFETY|'''mode''']] argument to [[mu_file_safety_check]]. If it contains the [[MU_FILE_SAFETY_OWNER_MISMATCH]] bit, the file owner UID can be set using the <tt>mu_dbm_safety_set_owner</tt> function.<br />
<br />
Whatever way was used to set them, the current safety criteria can be queried using the following two functions:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_safety_get_flags (mu_dbm_file_t db, int *flags);<br />
int mu_dbm_safety_get_owner (mu_dbm_file_t db, uid_t *uid);<br />
</syntaxhighlight><br />
<br />
== Opening a Database ==<br />
<br />
Once a <tt>mu_dbm_file_t</tt> is created, it can be opened:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_open (mu_dbm_file_t db, int flags, int mode);<br />
</syntaxhighlight> <br />
<br />
The function <tt>mu_dbm_open</tt> opens a database described by '''db'''. The '''flags''' argument specifies how to open the database. The valid values (declared in <tt>mailutils/stream.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/stream.h</ref>) are:<br />
<br />
;MU_STREAM_READ<br />
:Open database for reading only. If the database file does not exist, an error is returned.<br />
;MU_STREAM_RDWR<br />
:Open database for reading and writing. If the database file does not exist, it is created.<br />
;MU_STREAM_CREAT<br />
:Create an empty database and open it for reading and writing. If the database file already exists, all existing records will be removed from it.<br />
<br />
The '''mode''' argument supplies the file mode for newly created files. Its meaning is the same as in {{man|2|chmod}} call.<br />
<br />
==Database Lookups==<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_fetch (mu_dbm_file_t db, struct mu_dbm_datum const *key,<br />
struct mu_dbm_datum *ret);<br />
</syntaxhighlight><br />
<br />
The <tt>mu_dbm_fetch</tt> functions looks up in the database '''db''' a record whose key matches '''key'''. If such a record is found, its associated data are stored in '''ret''' and 0 is returned. If there is no such key in the database, the function returns [[MU_ERR_NOENT]]. If an error occurs, it returns [[MU_ERR_FAILURE]]. The textual error description can then be obtained using [[#mu_dbm_strerror|mu_dbm_strerror]].<br />
<br />
The memory for data returned in '''ret''' is allocated by the library. To reclaim this memory, use the [[#mu_dbm_datum_free|mu_dbm_datum_free]] function. If the '''ret''' parameter points to a datum initialized by a previous call to a <tt>libmu_dbm</tt> function (such as <tt>mu_dbm_fetch</tt>, <tt>mu_dbm_firstkey</tt>, etc.) it will be freed automatically. Therefore it is safe not to free existing datum before passing it as a third argument to <tt>mu_dbm_fetch</tt>.<br />
<br />
It is important to notice, however, that the datum pointed to by '''ret''' must always be initialized. This means, in practice, that it should either be returned from another <tt>libmu_dbm</tt> library call or initialized manually. For example:<br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
struct mu_dbm_datum key, content;<br />
int rc;<br />
<br />
/* Initialize search key */<br />
memset (&key, 0, sizeof key);<br />
key.mu_dptr = "user";<br />
key.mu_dsize = 4;<br />
/* Initialize content */<br />
memset (&content, 0, sizeof content);<br />
/* Look up the data */<br />
rc = mu_dbm_fetch (db, &key, &content);<br />
...<br />
/* Find another key: */<br />
key.mu_dptr = "hostname";<br />
key.mu_dsize = 8;<br />
/* It is OK not to re-set content here, because it was initialized<br />
by the previous call to mu_dbm_fetch and will be freed automatically. */<br />
rc = mu_dbm_fetch (db, &key, &content);<br />
...<br />
/* Free the content */<br />
mu_dbm_datum_free (&content);<br />
</syntaxhighlight><br />
<br />
==Storing Records==<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_store (mu_dbm_file_t db, struct mu_dbm_datum const *key,<br />
struct mu_dbm_datum const *content, int replace);<br />
</syntaxhighlight><br />
<br />
The function <tt>mu_dbm_store</tt> inserts or replaces records in the database.<br />
<br />
The parameters <tt>key</tt> and <tt>content</tt> supply the record key and associated data.<br />
The parameter <tt>replace</tt> determines behavior of the function if a record with such key already exists in the database. If <tt>replace</tt> is <tt>1</tt>, <tt>mu_dbm_store</tt> will replace the data part of the existing record with data from <tt>content</tt>. Otherwise, if <tt>replace</tt> is <tt>0</tt>, the function will leave the record unchanged and return [[MU_ERR_EXISTS]].<br />
<br />
The function returns <tt>0</tt> on success and [[MU_ERR_FAILURE]] on error. In the latter case the textual description of the error can be obtained using [[#mu_dbm_strerror|mu_dbm_strerror]].<br />
<br />
==Deleting a Record==<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_delete (mu_dbm_file_t db, struct mu_dbm_datum const *key);<br />
</syntaxhighlight><br />
<br />
This function deletes from the database a record with the given key. It returns 0 on success, [[MU_ERR_NOENT]], if there is no such key in the database and [[MU_ERR_FAILURE]] on error. In the latter case the textual description of the error can be obtained using [[#mu_dbm_strerror|mu_dbm_strerror]].<br />
<br />
==Sequential Access==<br />
The following two functions allow for accessing all items in the database:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_firstkey (mu_dbm_file_t db, struct mu_dbm_datum *ret);<br />
int mu_dbm_nextkey (mu_dbm_file_t db, struct mu_dbm_datum *ret);<br />
</syntaxhighlight><br />
<br />
The function <tt>mu_dbm_firstkey</tt> initializes <tt>db</tt> for sequential access and stores the first key in the datum pointed to by <tt>ret</tt>. The function returns <tt>0</tt> on success, [[MU_ERR_NOENT]] if the database is empty and [[MU_ERR_FAILURE]] on error. <br />
<br />
The function <tt>mu_dbm_nextkey</tt> takes a pointer to the datum returned by a prior call to<br />
either of the two functions and locates the key immediately following this one. On success, it stores the new key in that same datum and returns 0. It returns [[MU_ERR_NOENT]] if all keys in the database has been visited and [[MU_ERR_FAILURE]] if a database error occurred.<br />
<br />
This function takes care about the memory allocated for <tt>ret</tt>. This means that it is not necessary to call <tt>mu_dbm_datum_free (ret)</tt> neither before calling this function nor after it returns <tt>MU_ERR_NOENT</tt> (although doing so does not constitute an error). The usual sequential access code looks like:<br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
struct mu_dbm_datum key;<br />
int rc;<br />
<br />
memset (&key, 0, sizeof key);<br />
for (rc = mu_dbm_firstkey (db, &key); <br />
rc == 0; <br />
rc = mu_dbm_nextkey (db, &key))<br />
{<br />
do_something (&key);<br />
}<br />
if (rc != MU_ERR_NOENT)<br />
mu_dbm_datum_free (&key);<br />
</syntaxhighlight><br />
<br />
Notice, that sequential access does not imply any particular ordering in which the keys will be visited. It only guarantees that each key in the database will be visited exactly once, '''provided that no database updates take place within the loop'''. The latter condition is important. You cannot store or delete records while doing sequential access, because doing so can change the order in which keys are returned. In other words, the following is wrong:<br />
<br />
<syntaxhighlight lang="C"><br />
struct mu_dbm_datum key;<br />
int rc;<br />
<br />
memset (&key, 0, sizeof key);<br />
for (rc = mu_dbm_firstkey (db, &key); <br />
rc == 0; <br />
rc = mu_dbm_nextkey (db, &key))<br />
{<br />
if (key_matches_something (&key))<br />
/* This is wrong! */<br />
mu_dbm_delete (db, &key);<br />
}<br />
</syntaxhighlight><br />
<br />
==Additional Functions==<br />
<br />
The function <tt>mu_dbm_get_fd</tt> can be used to obtain file descriptors of the underlying database:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_get_fd (mu_dbm_file_t db, int *pag, int *dir);<br />
</syntaxhighlight><br />
<br />
The function returns two descriptors, because some libraries (namely, NDBM) keep databases in two files: so called ''page'' and ''directory'' files. If so, the descriptors of these files are returned in the memory locations pointed to by <tt>pag</tt> and <tt>dir</tt>, correspondingly. If the underlying library stores the database in a single file, the descriptor of this file will be stored in both <tt>pag</tt> and <tt>dir</tt>. In any case, <tt>dir</tt> can be <tt>NULL</tt> if that information is of no interest for the caller. However, <tt>pag</tt> can not be <tt>NULL</tt>, otherwise <tt>mu_dbm_get_fd</tt> will return <tt>ENOMEM</tt>.<br />
<br />
<div id="mu_dbm_init"></div><br />
The function <tt>mu_dbm_init</tt> initializes the library:<br />
<br />
<syntaxhighlight lang="C"><br />
void mu_dbm_init (void);<br />
</syntaxhighlight><br />
<br />
Normally it is not necessary to call this function because it is called automatically by any of the following functions: [[#mu_dbm_get_hint|<tt>mu_dbm_get_hint</tt>]], [[#mu_dbm_register|<tt>mu_dbm_register</tt>]], [[#mu_dbm_impl_iterator|<tt>mu_dbm_impl_iterator</tt>]], [[#Creating a Database Object|<tt>mu_dbm_create_from_url</tt>]] and [[#Creating a Database Object|<tt>mu_dbm_create</tt>]].<br />
<br />
==Return Codes==<br />
Apart from the return codes discussed above, each <tt>libmu_dbm</tt> function can return the following:<br />
<br />
;<tt>ENOMEM</tt><br />
:Not enough memory for the operation.<br />
;<tt>EINVAL</tt><br />
:The <tt>db</tt> or some other required argument is <tt>NULL</tt>.<br />
;<tt>MU_ERR_NOT_OPEN</tt><br />
:Database is not open. This error can be returned by any function taking <tt>mu_dbm_database_t</tt> as argument, except the following: <tt>mu_dbm_create_from_url</tt>, <tt>mu_dbm_create</tt>, <tt>mu_dbm_safety_get_owner</tt>, <tt>mu_dbm_safety_get_flags</tt>, <tt>mu_dbm_safety_set_owner</tt>, <tt>mu_dbm_safety_set_flags</tt>, <tt>mu_dbm_safety_check</tt>.<br />
;<tt>ENOSYS</tt><br />
:Function not implemented.<br />
<br />
==Error Reporting==<br />
<div id="mu_dbm_strerror"></div><br />
The functions from <tt>libmu_dbm</tt> return <tt>MU_ERR_FAILURE</tt> if an error occurred in the underlying database implementation. A textual description of this error can be obtained using the following call:<br />
<br />
<syntaxhighlight lang="C"><br />
char const *mu_dbm_strerror (mu_dbm_file_t db);<br />
</syntaxhighlight><br />
<br />
The pointer returned by this function must not be freed or its contents altered by the application.<br />
<br />
An example usage:<br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
rc = mu_dbm_store (db, &key, &contents, replace);<br />
if (rc)<br />
mu_error ("cannot store datum: %s",<br />
rc == MU_ERR_FAILURE ? <br />
mu_dbm_strerror (db) : mu_strerror (rc));<br />
</syntaxhighlight><br />
<br />
Notice how an appropriate error reporting function is selected in lines 4--5.<br />
<br />
==Closing the Database==<br />
<br />
An open database is closed using:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_close (mu_dbm_file_t db);<br />
</syntaxhighlight><br />
<br />
Unless intended for a subsequent re-opening, a closed database should be ''destroyed'' via a call to <tt>mu_dbm_destroy</tt>:<br />
<br />
<syntaxhighlight lang="C"><br />
void mu_dbm_destroy (mu_dbm_file_t *pdb);<br />
</syntaxhighlight><br />
<br />
This function reclaims the memory used by the <tt>mu_dbm_file_t</tt> object pointed to by its argument and initializes it to <tt>NULL</tt> before returning. Calling <tt>mu_dbm_destroy</tt> on an open database is OK: the function will call <tt>mu_dbm_close</tt> prior to freeing the memory. In fact, it is seldom necessary to call <tt>mu_dbm_close</tt> explicitly. Instead, it suffices to call <tt>mu_dbm_destroy</tt> once the database is no longer necessary.<br />
<br />
==API for Backend Implementors==<br />
<br />
The backend data and methods are defined in the following structure:<br />
<br />
<syntaxhighlight lang="C"><br />
struct mu_dbm_impl<br />
{<br />
char *_dbm_name;<br />
int (*_dbm_file_safety) (mu_dbm_file_t db, int mode, uid_t owner);<br />
int (*_dbm_get_fd) (mu_dbm_file_t db, int *pag, int *dir);<br />
int (*_dbm_open) (mu_dbm_file_t db, int flags, int mode);<br />
int (*_dbm_close) (mu_dbm_file_t db);<br />
int (*_dbm_fetch) (mu_dbm_file_t db, struct mu_dbm_datum const *key,<br />
struct mu_dbm_datum *ret);<br />
int (*_dbm_store) (mu_dbm_file_t db, struct mu_dbm_datum const *key,<br />
struct mu_dbm_datum const *contents, int replace);<br />
int (*_dbm_delete) (mu_dbm_file_t db,<br />
struct mu_dbm_datum const *key);<br />
int (*_dbm_firstkey) (mu_dbm_file_t db, struct mu_dbm_datum *ret);<br />
int (*_dbm_nextkey) (mu_dbm_file_t db, struct mu_dbm_datum *ret);<br />
void (*_dbm_datum_free) (struct mu_dbm_datum *datum);<br />
char const *(*_dbm_strerror) (mu_dbm_file_t db);<br />
};<br />
</syntaxhighlight><br />
<br />
The <tt>_dbm_name</tt> method names the backend. It will be used as a scheme in [[Database URL|URL]]s referring to databases of this type. The purpose of the remaining members should be pretty obvious. They correspond to API functions discussed above. Each API call is guaranteed to do the necessary error checking before calling the corresponding <tt>_dbm_</tt> method.<br />
<br />
The structure <tt>_mu_dbm_file</tt> is defined in <tt>mailutils/sys/dbm.h</tt> as follows:<br />
<br />
<syntaxhighlight lang="C"><br />
struct _mu_dbm_file<br />
{<br />
char *db_name; /* Database name */<br />
void *db_descr; /* Database descriptor */<br />
int db_safety_flags; /* Safety checks */<br />
uid_t db_owner; /* Database owner UID */<br />
struct mu_dbm_impl *db_sys; /* Pointer to the database implementation */<br />
union _mu_dbm_errno db_errno; /* Error description for the latest failed call */<br />
};<br />
</syntaxhighlight><br />
<br />
The members <tt>db_name</tt>, <tt>db_safety_flags</tt>, <tt>db_owner</tt> and <tt>db_sys</tt> are initialized by high level API. Implementation functions should initialize <tt>db_descr</tt> and <tt>db_errno</tt> as necessary. The <tt>db_descr</tt> method keeps a pointer to the implementation-specific data describing the database. For example, in a NDBM implementation, it can hold a pointer to the <tt>DBM</tt> structure for the open database:<br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
static int<br />
_ndbm_open (mu_dbm_file_t db, int flags, int mode)<br />
{<br />
DBM *dbm;<br />
<br />
/* Open the database and store its handle in db_descr */<br />
dbm = dbm_open (db->db_name, _mu_flags_to_ndbm (flags), mode);<br />
if (!dbm)<br />
return MU_ERR_FAILURE;<br />
db->db_descr = dbm;<br />
return 0;<br />
} <br />
</syntaxhighlight><br />
<br />
The <tt>db_errno</tt> member is intended to keep the latest error value for use by the <tt>_dbm_strerror</tt> method. To satisfy most implementation, it is able to keep both numeric and generic pointer data:<br />
<br />
<syntaxhighlight lang="C"><br />
union _mu_dbm_errno<br />
{<br />
int n; /* numeric value */<br />
void *p; /* pointer to an error object */<br />
};<br />
</syntaxhighlight><br />
<br />
The implementation methods are supposed to keep its value up to date. For example, in GDBM implementation, they store the value of [http://www.gnu.org.ua/software/gdbm/manual/html_node/Variables.html <tt>gdbm_errno</tt>] in <tt>db_errno.n</tt>:<br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
static int<br />
_gdbm_store (mu_dbm_file_t db,<br />
struct mu_dbm_datum const *key,<br />
struct mu_dbm_datum const *contents,<br />
int replace)<br />
{<br />
/* initialize local variables */<br />
...<br />
/* Do the underlying call and return: */<br />
switch (gdbm_store ((GDBM_FILE)db->db_descr, key_datum, content_datum, replace))<br />
{<br />
case 0:<br />
break;<br />
<br />
case 1:<br />
return MU_ERR_EXISTS;<br />
<br />
case -1:<br />
db->db_errno.n = gdbm_errno;<br />
return MU_ERR_FAILURE;<br />
}<br />
} <br />
</syntaxhighlight><br />
<br />
A corresponding <tt>_dbm_strerror</tt> implementation uses the stored value:<br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
static char const *<br />
_gdbm_strerror (mu_dbm_file_t db)<br />
{<br />
return gdbm_strerror (db->db_errno.n);<br />
}<br />
</syntaxhighlight><br />
<br />
<div id="mu_dbm_register"></div><br />
A properly initialized <tt>mu_dbm_impl</tt> structure must be ''registered'' with the library by calling the following function:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_register (struct mu_dbm_impl *impl);<br />
</syntaxhighlight><br />
<br />
Once done, it becomes avaiable for use by the API.<br />
<br />
<div id="mu_dbm_impl_iterator"></div><br />
Registered implementations can be accessed via an [[iterator]] returned by the <tt>mu_dbm_impl_iterator</tt> function:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_dbm_impl_iterator (mu_iterator_t *itr);<br />
</syntaxhighlight><br />
<br />
For example, the following code snippet lists avaialble DBM implementations:<br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
mu_iterator_t itr;<br />
<br />
mu_dbm_impl_iterator (&itr);<br />
for (mu_iterator_first (itr), i = 0; !mu_iterator_is_done (itr);<br />
mu_iterator_next (itr), i++)<br />
{<br />
struct mu_dbm_impl *impl;<br />
<br />
mu_iterator_current (itr, (void**)&impl);<br />
fprintf (stream, " ");<br />
fprintf (stream, "%s", impl->_dbm_name);<br />
}<br />
fputc ('\n', stream);<br />
mu_iterator_destroy (&itr);<br />
</syntaxhighlight><br />
<br />
For an example of using the backend implementation API see <tt>libmu_dbm/gdbm.c</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/libmu_dbm/gdbm.c</ref>.<br />
<br />
==Notes==<br />
<references/><br />
<br />
[[Category:DBM]]<br />
[[Category:C API]]<br />
[[Category:Libraries]]</div>Grayhttps://mailutils.org/usqay/index.php?title=File_Safety_Functions&diff=537File Safety Functions2023-10-16T13:29:57Z<p>Gray: </p>
<hr />
<div>Functions for running [[File Safety Checks|file safety checks]] are implemented in [[libmailutils]]. The corresponding prototypes and constants are declared in the header<br />
<tt>mailutils/util.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/util.h</ref>.<br />
<br />
== mu_file_safety_check ==<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_file_safety_check (const char *filename, <br />
int mode,<br />
uid_t uid,<br />
mu_list_t idlist);<br />
</syntaxhighlight><br />
<br />
The function <tt>mu_file_safety_check</tt> checks whether the file '''filename''' satisfies safety checks described by the '''mode''' and '''uid''' arguments.<br />
<br />
Its arguments are:<br />
<br />
;filename<br />
: Name of the file to check.<br />
;mode<br />
: A bitmap specifying the checks to perform. It can be constructed as a bitwise ''OR'' of one or more of the following flags, corresponding to the main [[File Safety Checks#safety-checks|safety checks]]:<br />
<div id="MU_FILE_SAFETY"></div><br />
:; MU_FILE_SAFETY_OWNER_MISMATCH<br />
:: Check whether the file owner UID equals to the '''uid''' argument.<br />
:; MU_FILE_SAFETY_WORLD_WRITABLE<br />
:: Fail if the file is world writable ('''awrfil''')<br />
:; MU_FILE_SAFETY_GROUP_WRITABLE<br />
:: Fail if the file is group writable ('''gwrfil''')<br />
:; MU_FILE_SAFETY_LINKED_WRDIR<br />
;: Fail if the file is a symbolic link located in a (world- or group-) writable directory ('''linkwrdir''')<br />
:; MU_FILE_SAFETY_DIR_IWGRP<br />
;: Fail if the file is located in a group-writable directory ('''gwrdir''')<br />
:; MU_FILE_SAFETY_DIR_IWOTH<br />
;: Fail if the file is located in a world-writable directory ('''awrdir''')<br />
:; MU_FILE_SAFETY_WORLD_READABLE<br />
:: Fail if the file is world readable ('''awrfil''')<br />
:; MU_FILE_SAFETY_GROUP_READABLE<br />
:: Fail if the file is group readable ('''grdfil''')<br />
<br />
: Additionally, the following two defines are provided:<br />
:; MU_FILE_SAFETY_ALL<br />
:: All the above checks <br />
:; MU_FILE_SAFETY_NONE<br />
:: No checks<br />
;uid<br />
: UID the file should be owned by, if the <tt>MU_FILE_SAFETY_OWNER_MISMATCH</tt> mode is specified.<br />
;idlist<br />
: A list used to avoid checking the same file twice. It is useful if '''mu_file_safety_check''' is to be called several times. At the first call to the function, this argument should contain a newly created list. The function uses this list to keep record of the device and inode numbers of processed files. If '''mu_file_safety_check''' determines that the file it is about to check is already entered in this list, it will immediately return <tt>MU_ERR_EXISTS</tt>.<br />
: If this is not needed, this argument should be <tt>NULL</tt>.<br />
<br />
<div id="MU_ERR_PERM"></div><br />
The '''mu_file_safety_check''' returns <tt>0</tt> if the file passes all checks, or one of the following error codes otherwise:<br />
<br />
;MU_ERR_PERM_OWNER_MISMATCH<br />
:File owner does not match the requested UID.<br />
;MU_ERR_PERM_WORLD_WRITABLE<br />
:File is world writable<br />
;MU_ERR_PERM_GROUP_WRITABLE<br />
:File is group writable<br />
;MU_ERR_PERM_LINKED_WRDIR<br />
:Linked file in a writable directory<br />
;MU_ERR_PERM_DIR_IWGRP<br />
:File resides in group writable directory<br />
;MU_ERR_PERM_DIR_IWOTH<br />
:File resides in world writable directory<br />
;MU_ERR_PERM_WORLD_READABLE<br />
:File is world readable<br />
;MU_ERR_PERM_GROUP_READABLE<br />
:File is group readable<br />
;MU_ERR_EXISTS<br />
:The file has already been checked before (see the description of the '''idlist''' argument, above).<br />
<br />
==mu_file_safety_name_to_code==<br />
<syntaxhighlight lang="C"><br />
int mu_file_safety_name_to_code (const char *name, int *pcode);<br />
</syntaxhighlight><br />
<br />
This function converts the symbolic [[File Safety Checks#safety-checks|safety check name]] '''name''' to the corresponding [[#MU_FILE_SAFETY|<tt>MU_FILE_SAFETY</tt> constant]].<br />
<br />
If the conversion succeeds, the function stores the result in the memory location pointed to by the '''pcode''' argument and returns 0. If '''name''' does not match any safety check name, the function returns <tt>MU_ERR_NOENT</tt>.<br />
<br />
==mu_file_safety_name_to_error==<br />
<syntaxhighlight lang="C"><br />
int mu_file_safety_name_to_error (const char *name, int *pcode);<br />
</syntaxhighlight><br />
<br />
This function converts the symbolic [[File Safety Checks#safety-checks|safety check name]] '''name''' to the corresponding <tt>MU_ERR_PERM</tt> error code.<br />
<br />
If the conversion succeeds, the function stores the result in the memory location pointed to by the '''pcode''' argument and returns 0. If '''name''' does not match any safety check name, the function returns <tt>MU_ERR_NOENT</tt>.<br />
<br />
== Safety Checks, Modes and Error Codes ==<br />
<br />
The following table summarizes the available safety checks and their corresponding mode and<br />
error codes:<br />
<br />
{| style="border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"<br />
! style="border-style: solid; border-width: 1px"|Check name<br />
! style="border-style: solid; border-width: 1px"|Mode<br />
! style="border-style: solid; border-width: 1px"|Error code<br />
|-<br />
| style="border-style: solid; border-width: 1px"|N/A<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_OWNER_MISMATCH <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_OWNER_MISMATCH <br />
|-<br />
| style="border-style: solid; border-width: 1px"|awrfil <br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_WORLD_WRITABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_WORLD_WRITABLE <br />
|-<br />
| style="border-style: solid; border-width: 1px"|gwrfil<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_GROUP_WRITABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_GROUP_WRITABLE <br />
|-<br />
| style="border-style: solid; border-width: 1px"|linkwrdir<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_LINKED_WRDIR<br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_LINKED_WRDIR <br />
|-<br />
| style="border-style: solid; border-width: 1px"|awrdir<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_DIR_IWGRP <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_DIR_IWGRP <br />
|-<br />
| style="border-style: solid; border-width: 1px"|gwrdir<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_DIR_IWOTH <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_DIR_IWOTH <br />
|-<br />
| style="border-style: solid; border-width: 1px"|ardfil<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_WORLD_READABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_WORLD_READABLE <br />
|-<br />
| style="border-style: solid; border-width: 1px"|grdfil <br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_GROUP_READABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_GROUP_READABLE <br />
|}<br />
<br />
==Example==<br />
The following example implements a utility which applies the requested safety checks to a set of files. Both <br />
check modes and file names are supplied in the command line and can be interspersed. Each check mode begins with a plus sign, in which case the corresponding check is enabled, or with a minus sign in which case it is disabled. <br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
#include <stdio.h><br />
#include <stdlib.h><br />
#include <unistd.h><br />
#include <mailutils/types.h><br />
#include <mailutils/error.h><br />
#include <mailutils/errno.h><br />
#include <mailutils/util.h><br />
<br />
int<br />
main (int argc, char **argv)<br />
{<br />
int i;<br />
int mode = MU_FILE_SAFETY_OWNER_MISMATCH, rc, m;<br />
mu_list_t idlist;<br />
uid_t uid;<br />
<br />
if (argc == 1)<br />
{<br />
mu_error ("usage: %s [+-]mode... file...", argv[0]);<br />
exit (1);<br />
}<br />
<br />
rc = mu_list_create (&idlist);<br />
if (rc)<br />
{<br />
mu_error ("mu_list_create: %s", mu_strerror (rc));<br />
exit (1);<br />
}<br />
uid = getuid ();<br />
<br />
for (i = 1; i < argc; i++)<br />
{<br />
if (argv[i][0] == '-' || argv[i][0] == '+')<br />
{<br />
rc = mu_file_safety_name_to_code (argv[i] + 1, &m);<br />
if (rc)<br />
{<br />
mu_error ("%s: %s", argv[i], mu_strerror (rc));<br />
exit (1);<br />
}<br />
if (argv[i][0] == '-')<br />
mode &= ~m;<br />
else<br />
mode |= m;<br />
}<br />
else<br />
{<br />
rc = mu_file_safety_check (argv[i], mode, uid, idlist);<br />
printf ("%s: %s\n", argv[i], mu_strerror (rc));<br />
}<br />
}<br />
exit (0);<br />
}<br />
</syntaxhighlight><br />
<br />
==Notes==<br />
<references/><br />
<br />
== See also ==<br />
* [[File Safety Checks]]<br />
<br />
[[Category:Safety]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=File_Safety_Functions&diff=536File Safety Functions2023-10-16T13:29:20Z<p>Gray: </p>
<hr />
<div>Functions for running [[File Safety Checks|file safety checks]] are implemented in [[libmailutils]]. The corresponding prototypes and constants are declared in the header<br />
<tt>mailutils/util.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/util.h</ref>.<br />
<br />
== mu_file_safety_check ==<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_file_safety_check (const char *filename, <br />
int mode,<br />
uid_t uid,<br />
mu_list_t idlist);<br />
</syntaxhighlight><br />
<br />
The function <tt>mu_file_safety_check</tt> checks whether the file '''filename''' satisfies safety checks described by the '''mode''' and '''uid''' arguments.<br />
<br />
Its arguments are:<br />
<br />
;filename<br />
: Name of the file to check.<br />
;mode<br />
: A bitmap specifying the checks to perform. It can be constructed as a bitwise ''OR'' of one or more of the following flags, corresponding to the main [[File Safety Checks#safety-checks|safety checks]]:<br />
<div id="MU_FILE_SAFETY"></div><br />
:; MU_FILE_SAFETY_OWNER_MISMATCH<br />
:: Check whether the file owner UID equals to the '''uid''' argument.<br />
:; MU_FILE_SAFETY_WORLD_WRITABLE<br />
:: Fail if the file is world writable ('''awrfil''')<br />
:; MU_FILE_SAFETY_GROUP_WRITABLE<br />
:: Fail if the file is group writable ('''gwrfil''')<br />
:; MU_FILE_SAFETY_LINKED_WRDIR<br />
;: Fail if the file is a symbolic link located in a (world- or group-) writable directory ('''linkwrdir''')<br />
:; MU_FILE_SAFETY_DIR_IWGRP<br />
;: Fail if the file is located in a group-writable directory ('''gwrdir''')<br />
:; MU_FILE_SAFETY_DIR_IWOTH<br />
;: Fail if the file is located in a world-writable directory ('''awrdir''')<br />
:; MU_FILE_SAFETY_WORLD_READABLE<br />
:: Fail if the file is world readable ('''awrfil''')<br />
:; MU_FILE_SAFETY_GROUP_READABLE<br />
:: Fail if the file is group readable ('''grdfil''')<br />
<br />
: Additionally, the following two defines are provided:<br />
:; MU_FILE_SAFETY_ALL<br />
:: All the above checks <br />
:; MU_FILE_SAFETY_NONE<br />
:: No checks<br />
;uid<br />
: UID the file should be owned by, if the <tt>MU_FILE_SAFETY_OWNER_MISMATCH</tt> mode is specified.<br />
;idlist<br />
: A list used to avoid checking the same file twice. It is useful if '''mu_file_safety_check''' is to be called several times. At the first call to the function, this argument should contain a newly created list. The function uses this list to keep record of the device and inode numbers of processed files. If '''mu_file_safety_check''' determines that the file it is about to check is already entered in this list, it will immediately return <tt>MU_ERR_EXISTS</tt>.<br />
: If this is not needed, this argument should be <tt>NULL</tt>.<br />
<br />
<div id="MU_ERR_PERM"></div><br />
The '''mu_file_safety_check''' returns <tt>0</tt> if the file passes all checks, or one of the following error codes otherwise:<br />
<br />
;MU_ERR_PERM_OWNER_MISMATCH<br />
:File owner does not match the requested UID.<br />
;MU_ERR_PERM_WORLD_WRITABLE<br />
:File is world writable<br />
;MU_ERR_PERM_GROUP_WRITABLE<br />
:File is group writable<br />
;MU_ERR_PERM_LINKED_WRDIR<br />
:Linked file in a writable directory<br />
;MU_ERR_PERM_DIR_IWGRP<br />
:File resides in group writable directory<br />
;MU_ERR_PERM_DIR_IWOTH<br />
:File resides in world writable directory<br />
;MU_ERR_PERM_WORLD_READABLE<br />
:File is world readable<br />
;MU_ERR_PERM_GROUP_READABLE<br />
:File is group readable<br />
;MU_ERR_EXISTS<br />
:The file has already been checked before (see the description of the '''idlist''' argument, above).<br />
<br />
==mu_file_safety_name_to_code==<br />
<source lang="C"><br />
int mu_file_safety_name_to_code (const char *name, int *pcode);<br />
</source><br />
<br />
This function converts the symbolic [[File Safety Checks#safety-checks|safety check name]] '''name''' to the corresponding [[#MU_FILE_SAFETY|<tt>MU_FILE_SAFETY</tt> constant]].<br />
<br />
If the conversion succeeds, the function stores the result in the memory location pointed to by the '''pcode''' argument and returns 0. If '''name''' does not match any safety check name, the function returns <tt>MU_ERR_NOENT</tt>.<br />
<br />
==mu_file_safety_name_to_error==<br />
<syntaxhighlight lang="C"><br />
int mu_file_safety_name_to_error (const char *name, int *pcode);<br />
</syntaxhighlight><br />
<br />
This function converts the symbolic [[File Safety Checks#safety-checks|safety check name]] '''name''' to the corresponding <tt>MU_ERR_PERM</tt> error code.<br />
<br />
If the conversion succeeds, the function stores the result in the memory location pointed to by the '''pcode''' argument and returns 0. If '''name''' does not match any safety check name, the function returns <tt>MU_ERR_NOENT</tt>.<br />
<br />
== Safety Checks, Modes and Error Codes ==<br />
<br />
The following table summarizes the available safety checks and their corresponding mode and<br />
error codes:<br />
<br />
{| style="border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"<br />
! style="border-style: solid; border-width: 1px"|Check name<br />
! style="border-style: solid; border-width: 1px"|Mode<br />
! style="border-style: solid; border-width: 1px"|Error code<br />
|-<br />
| style="border-style: solid; border-width: 1px"|N/A<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_OWNER_MISMATCH <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_OWNER_MISMATCH <br />
|-<br />
| style="border-style: solid; border-width: 1px"|awrfil <br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_WORLD_WRITABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_WORLD_WRITABLE <br />
|-<br />
| style="border-style: solid; border-width: 1px"|gwrfil<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_GROUP_WRITABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_GROUP_WRITABLE <br />
|-<br />
| style="border-style: solid; border-width: 1px"|linkwrdir<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_LINKED_WRDIR<br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_LINKED_WRDIR <br />
|-<br />
| style="border-style: solid; border-width: 1px"|awrdir<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_DIR_IWGRP <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_DIR_IWGRP <br />
|-<br />
| style="border-style: solid; border-width: 1px"|gwrdir<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_DIR_IWOTH <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_DIR_IWOTH <br />
|-<br />
| style="border-style: solid; border-width: 1px"|ardfil<br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_WORLD_READABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_WORLD_READABLE <br />
|-<br />
| style="border-style: solid; border-width: 1px"|grdfil <br />
| style="border-style: solid; border-width: 1px"|MU_FILE_SAFETY_GROUP_READABLE <br />
| style="border-style: solid; border-width: 1px"|MU_ERR_PERM_GROUP_READABLE <br />
|}<br />
<br />
==Example==<br />
The following example implements a utility which applies the requested safety checks to a set of files. Both <br />
check modes and file names are supplied in the command line and can be interspersed. Each check mode begins with a plus sign, in which case the corresponding check is enabled, or with a minus sign in which case it is disabled. <br />
<br />
<syntaxhighlight lang="C" line="GESHI_NORMAL_LINE_NUMBERS"><br />
#include <stdio.h><br />
#include <stdlib.h><br />
#include <unistd.h><br />
#include <mailutils/types.h><br />
#include <mailutils/error.h><br />
#include <mailutils/errno.h><br />
#include <mailutils/util.h><br />
<br />
int<br />
main (int argc, char **argv)<br />
{<br />
int i;<br />
int mode = MU_FILE_SAFETY_OWNER_MISMATCH, rc, m;<br />
mu_list_t idlist;<br />
uid_t uid;<br />
<br />
if (argc == 1)<br />
{<br />
mu_error ("usage: %s [+-]mode... file...", argv[0]);<br />
exit (1);<br />
}<br />
<br />
rc = mu_list_create (&idlist);<br />
if (rc)<br />
{<br />
mu_error ("mu_list_create: %s", mu_strerror (rc));<br />
exit (1);<br />
}<br />
uid = getuid ();<br />
<br />
for (i = 1; i < argc; i++)<br />
{<br />
if (argv[i][0] == '-' || argv[i][0] == '+')<br />
{<br />
rc = mu_file_safety_name_to_code (argv[i] + 1, &m);<br />
if (rc)<br />
{<br />
mu_error ("%s: %s", argv[i], mu_strerror (rc));<br />
exit (1);<br />
}<br />
if (argv[i][0] == '-')<br />
mode &= ~m;<br />
else<br />
mode |= m;<br />
}<br />
else<br />
{<br />
rc = mu_file_safety_check (argv[i], mode, uid, idlist);<br />
printf ("%s: %s\n", argv[i], mu_strerror (rc));<br />
}<br />
}<br />
exit (0);<br />
}<br />
</syntaxhighlight><br />
<br />
==Notes==<br />
<references/><br />
<br />
== See also ==<br />
* [[File Safety Checks]]<br />
<br />
[[Category:Safety]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Debugging_functions&diff=535Debugging functions2023-10-16T13:28:23Z<p>Gray: </p>
<hr />
<div>Mailutils API provides programmers with three ways of outputting additional debugging information:<br />
<br />
# Via the [[#mu_debug|<tt>mu_debug</tt>]] macro.<br />
# Via the [[#mu_debug_log|<tt>mu_debug_log</tt>]] functions.<br />
# By writing directly to the [[#mu_strerr|<tt>mu_strerr</tt>]] stream.<br />
<br />
The two former are the most often used, and the latter is a rather low-level method suitable when the desired output cannot be achieved by other means.<br />
<br />
== Categories and Levels ==<br />
<br />
Although debugging output is often regarded as being useful for developers only, it is quite often helpful for regular users. Therefore it is important to give user a possibility to choose what debugging information he needs and how verbose he wants it to be.<br />
<br />
Mailutils achieves this using a concept of debugging categories and levels. A ''category'' comprises all debugging information related to a certain part of the functionality of a program. For example, the category ''acl'' means everything related to access control lists.<br />
A ''level'' controls what information is desired in the given category.<br />
<br />
An easy to use [[Debug level|symbolic notation]] is provided which allows users to select the<br />
desired categories and associated levels from the command line and<br />
configuration files. In this article we will look at the internal aspects of these notions, from the point of view of a programmer.<br />
<br />
Categories are represented by integer numbers. There is a set of built-in categories, described in file <tt>libmailutils/diag/debcat</tt><ref>[http://git.gnu.org.ua/cgit/mailutils.git/tree/libmailutils/diag/debcat Predefined debug categories] (Git repository)</ref> and the <tt>include/mailutils/sys/debcat.h</tt> header, which is generated from it. These categories can be referred to in program text by their macro names. For example, the category ''auth'' is available under the name <tt>MU_DEBCAT_AUTH</tt>, and so on. To access these names, include the file <tt>mailutils/debug.h</tt>.<br />
<br />
Applications can also register their own category names. It is useful, for example, for loadable libraries. A new category is registered by calling the <tt>mu_debug_register_category</tt><br />
function:<br />
<br />
<syntaxhighlight lang="C"><br />
size_t mu_debug_register_category (char *name);<br />
</syntaxhighlight><br />
<br />
The ''name'' argument supplies the symbolic name for this category, under which it will be available for users. The function returns a ''category index'' which can subsequently be used in ''mu_debug*'' calls (see below).<br />
<br />
Levels are implemented as integer numbers, which can be combined to form level bitmasks. There are 12 levels available:<br />
<br />
;MU_DEBUG_ERROR<br />
:Mild error conditions which are normally not reported, but passed back to the caller layers for handling. <br />
;MU_DEBUG_TRACE0 through MU_DEBUG_TRACE9<br />
:Ten levels of verbosity, from minimal to the maximum amount of output. <br />
;MU_DEBUG_PROT<br />
:Displays network protocol interaction, where applicable. <br />
<br />
Two macros are available for creating level masks:<br />
<br />
<tt>MU_DEBUG_LEVEL_MASK(''n'')</tt> creates a level mask for the level ''n''. Such masks can be combined using binary 'OR', e.g.<br />
<br />
MU_DEBUG_LEVEL_MASK(MU_DEBUG_TRACE6) | MU_DEBUG_LEVEL_MASK(MU_DEBUG_PROT)<br />
<br />
<tt>MU_DEBUG_LEVEL_UPTO(''n'')</tt> creates a mask containing all levels from <tt>MU_DEBUG_ERROR</tt> up to and including ''n''.<br />
<br />
The function <tt>mu_debug_level_p</tt> is provided to check whether a given level is set<br />
for a given category:<br />
<br />
<syntaxhighlight lang="C"><br />
int mu_debug_level_p (int category, int level);<br />
</syntaxhighlight><br />
<br />
<div id="mu_debug"></div><br />
== The <tt>mu_debug</tt> macro ==<br />
<br />
The ''mu_debug'' macro is the basic mechanism for implementing debugging output in programs:<br />
<br />
mu_debug(''category'', ''level'', (''args''))<br />
<br />
The first two arguments specify the category and level, and the third one must be an argument list suitable for the ''mu_debug_log'' invocation. <br />
{{Note|''args'' must always be enclosed in an extra pair of parentheses.}}<br />
<br />
The macro tests if the ''level'' is set for the given ''category'', and if so, it invokes <tt>mu_debug_log</tt> with the argument list (''args''). Additionally. if the <tt>mu_debug_line_info</tt> global variable is set, it arranges for the current source location to be shown in the output. For example, the following invocation:<br />
<br />
mu_debug (MU_DEBCAT_MAILBOX, MU_DEBUG_TRACE1, <br />
("mbox_scan (%s) returned %d", mud->name, result));<br />
<br />
will format the argument list given as its third argument if the ''mailbox.=trace1'' [[Debug level|level]] is set.<br />
<br />
<div id="mu_debug_log"></div><br />
==The <tt>mu_debug_log</tt> function family==<br />
<br />
The [[mu_debug_log]] functions are the mechanism used by the <tt>mu_debug</tt> macro to do the actual output:<br />
<br />
<syntaxhighlight lang="C"><br />
void mu_debug_log (const char *fmt, ...);<br />
void mu_debug_log_begin (const char *fmt, ...);<br />
void mu_debug_log_cont (const char *fmt, ...);<br />
void mu_debug_log_end (const char *fmt, ...);<br />
</syntaxhighlight><br />
<br />
All functions are variadic, with their argument ''fmt'' argument being a usual ''printf'' format specification<ref>[http://pubs.opengroup.org/onlinepubs/009695399/functions/printf.html The printf function]</ref>, and the rest of arguments supplying the actual data to output.<br />
<br />
The <tt>mu_debug_log</tt> function formats its arguments, and then sends the formatted data '''terminated with a newline''' character to the ''mu_strerr'' stream. Therefore, the ''fmt'' argument to this function must not contain terminating <tt>\n</tt>.<br />
<br />
If you need to output debugging information in several chunks but want these chunks to form a single line on output, do as follows:<br />
<br />
# Call <tt>mu_debug_log_begin</tt>. This function prepares the log stream for subsequent continuous output, formats its data and sends them down the stream as the first chunk.<br />
# Call <tt>mu_debug_log_cont</tt> as much times as needed (perhaps within a loop) to format more parts of the output sequence. Neither <tt>mu_debug_log_begin</tt> nor <tt>mu_debug_log_cont</tt> add newlines to their output, so until now the output is not flushed.<br />
# Send the lest portion of data using the <tt>mu_debug_log_end</tt> call. After formatting its data, the function sends a terminating newline, thereby flushing the formatted output to the log stream.<br />
<br />
You can also terminate the line with a call to <tt>mu_debug_log_nl()</tt> function, if there is no more data left for output:<br />
<br />
<syntaxhighlight lang="C"><br />
void mu_debug_log_nl (void);<br />
</syntaxhighlight><br />
<br />
The following code fragment illustrates this approach.<br />
<br />
<syntaxhighlight lang="C"><br />
if (mu_debug_level_p (MU_DEBCAT_FILTER, MU_DEBUG_TRACE1))<br />
{<br />
int i;<br />
<br />
mu_debug_log_begin ("Command line was:");<br />
for (i = 0; argv[i]; i++)<br />
mu_debug_log_cont (" %s", argv[i]);<br />
mu_debug_log_nl ();<br />
}<br />
</syntaxhighlight><br />
<br />
This code checks if the [[Debug level|level]] ''filter.=trace1'' is set, and if so formats<br />
the array <tt>char **argv</tt> into the log output stream.<br />
<br />
<div id="mu_strerr"></div><br />
== The ''mu_strerr'' stream ==<br />
<br />
The stream <tt>mu_strerr</tt> is a Mailutils counterpart of the traditional <tt>stderr</tt> stream, except that it provides much more possibilities. All writes to this stream are directed to whatever log transport stream was specified in the Mailutils configuration file.<br />
<br />
The stream is line-buffered, so the output gets flushed after each <tt>\n</tt> character written to it. Upon writing to the transport stream, a ''diagnostic prefix'' is output before each lineful of data. The prefix consists of:<br />
<br />
# The value of <tt>mu_log_tag</tt> variable, followed by a colon and space character;<br />
# Input stream [[error location|location]], if it is set;<br />
# Optionally, if <tt>mu_log_print_severity</tt> is set, the severity designator, such as <tt>debug</tt> for debugging information, <tt>warning</tt> for warnings, etc.<br />
<br />
<tt>Mu_strerr</tt> is an instance of [[log stream]], and supports all ioctls and format directives supported by it. For example, to set [[error location|location]] you can either use<br />
the [[MU_IOCTL_LOGSTREAM]] ioctl, or (to set it temporarily, for this line of output only), the <br />
<tt>f</tt> and <tt>l</tt> [[log escape]]s, as shown in the example code below:<br />
<br />
<syntaxhighlight lang="C"><br />
mu_stream_printf (mu_strerr, "\033f<%d>%s\033l<%d>%s", strlen (file), file, line, <br />
"bad input") <br />
</syntaxhighlight><br />
<br />
<br />
==Notes==<br />
<references/><br />
<br />
[[Category:Debugging]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Xml_(filter)&diff=534Xml (filter)2023-10-16T13:26:45Z<p>Gray: </p>
<hr />
<div>In encode mode, the <tt>xml</tt> filter converts input stream (which must contain valid UTF-8 characters) into a form suitable for inclusion into a XML or HTML document, i.e. it replaces <tt>&lt;</tt>, <tt>&gt;</tt>, and <tt>&amp;</tt> with <tt>&amp;lt;</tt>, <tt>&amp;gt;</tt>, and <tt>&amp;amp;</tt>, correspondingly, and replaces [http://www.w3.org/TR/xml/#charsets invalid characters] with their [http://www.w3.org/TR/xml/#dt-charref numeric character reference] representation.<br />
<br />
In ''decode'' mode, a reverse operation is performed.<br />
<br />
The filter does not take arguments. <br />
<br />
The following object, declared in '''mailutils/filter.h''' describes the filter:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_xml_filter;<br />
</syntaxhighlight><br />
<br />
The example below shows how to create an instance of this filter in encode mode for reading:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "xml", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
== See also ==<br />
<br />
* [[htmlent]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Quoted-printable&diff=533Quoted-printable2023-10-16T13:26:15Z<p>Gray: </p>
<hr />
<div>The <tt>quoted-printable</tt> and <tt>Q</tt> [[filter]]s encode or decode the input using the [http://en.wikipedia.org/wiki/quoted-printable quoted-printable] encoding.<br />
<br />
These filters are described by the following objects (declared <tt>mailutils/filter.h</tt>):<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_qp_filter;<br />
extern mu_filter_record_t mu_rfc_2047_Q_filter;<br />
</syntaxhighlight><br />
<br />
The following example illustrates how to create a read-only filter for encoding the input stream to ''quoted-printable'' form:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
<br />
rc = mu_filter_create (&flt, input, "quoted-printable", MU_FILTER_ENCODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
== See also ==<br />
<br />
* [[base64 (filter)|Base64]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Linelen&diff=532Linelen2023-10-16T13:25:48Z<p>Gray: </p>
<hr />
<div>The <tt>linelen</tt> [[filter]] limits the length of the output lines to a certain number of octets. It operates in [[MU_FILTER_ENCODE|encode]] mode only and requires a single parameter: the desired output length in octets.<br />
This filter makes no attempt to analyze the lexical structure of the input: the newline caracters are inserted<br />
when the length of the output line reaches a predefined maximum. Any "\n" characters present in the input are<br />
taken into account when computing the input line length.<br />
<br />
The following code creates an instance of read-only <tt>linelen</tt> stream which breaks the input stream (<tt>mu_stream_t input</tt>, which is supposed to have been initialized previously) to lines of no more than 76 characters.<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
char *argv[] = { "linelen", "76", NULL };<br />
<br />
rc = mu_filter_chain_create (&flt, input, MU_FILTER_ENCODE, MU_STREAM_READ, 2, argv);<br />
</syntaxhighlight><br />
<br />
The object describing this filter is declared in <tt>mailutils/filter.h</tt> as follows:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_linelen_filter;<br />
</syntaxhighlight><br />
<br />
== See also ==<br />
<br />
* [[base64 (filter)|base64]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Linecon&diff=531Linecon2023-10-16T13:25:20Z<p>Gray: </p>
<hr />
<div>''Linecon'' is a Mailutils [[filter]] implementing a familiar UNIX line-continuation facility. It removes from the input stream any newline character immediately preceded by a backslash. This filter operates only in [[MU_FILTER_DECODE|decode mode]].<br />
<br />
The creation sequence allows for the following [[filter option|option]]:<br />
<br />
<tt>-i ''STR''</tt><br />
<br />
This option enables the [[line number information facility]]. This facility emits current input line number (prefixed with ''STR'') after each contiguous sequence of one or more removed newline characters. It is useful for implementing parsers which are normally supposed to identify eventual erroneous lines with their input line numbers. The following example creates a read-only instance of this filter with the line number information facility enabled:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
char *argv[] = { "linecon", "-i", "#line ", NULL },<br />
<br />
initialize_input_stream (&stream);<br />
rc = mu_filter_create_args (&flt, input, argv[0], 3, argv, MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Inline-comment&diff=530Inline-comment2023-10-16T13:24:56Z<p>Gray: </p>
<hr />
<div>== Introduction ==<br />
<br />
The <tt>inline-comment</tt> filter in [[MU_FILTER_DECODE|decode mode]] removes [http://en.wikipedia.org/wiki/Inline_comment inline comments] from the input stream. <br />
<br />
In [[MU_FILTER_ENCODE|encode mode]] it outputs a given byte sequence at the beginning of each output line.<br />
<br />
=== Decode mode ===<br />
<br />
In decode mode, the filter removes all lines beginning with a ''comment sequence'' from the input. The default comment sequence is <tt>;</tt> (a semicolon). The initialization of the <tt>inline-stream</tt> in this default mode is shown in the following example:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
To change the comment sequence supply the new sequence as the first argument. For example, the following filter will remove any lines starting with a <tt>rem</tt>:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
char *argv[] = { "inline-comment", "rem", NULL },<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create_args (&flt, input, "inline-comment", 2, argv, MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
Notice that the above filter will remove any line starting with the <tt>rem</tt> characters, for example:<br />
<br />
<pre><br />
rem A comment.<br />
remark that should not be removed.<br />
</pre><br />
<br />
Removing of the second line seems wrong in most cases, therefore the filter supports a special ''whitespace-must-follow mode'', in which it recognizes the comment sequence only when it is immediatly followed by a whitespace character. This mode is enabled by the <br />
<tt>-S</tt> option to the filter. E.g.:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
char *argv[] = { "inline-comment", "rem", "-S", NULL },<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create_args (&flt, input, "inline-comment", 3, argv, MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
The following [[filter options|options]] modify the default behavior:<br />
<br />
; -i ''STR''<br />
: Emit line number information after each contiguous sequence of removed lines. ''STR'' supplies "information starter" -- a sequence of characters which is output before the actual line number.<br />
; -r <br />
: Remove empty lines, i.e. the ones that contain only whitespace characters.<br />
; -s<br />
: Squeeze whitespace. Each sequence of two or more whitespace characters encountered on input is replaced by a single space character on output.<br />
; -S <br />
: A ''whitespace-must-follow mode''. A comment sequence is recognized only if followed by a whitespace character. The character itself is retained on output. <br />
<br />
=== Encode mode ===<br />
<br />
In [[MU_FILTER_ENCODE|encode mode]] the ''inline-comment'' filter adds a comment-starter sequence at the beginning of each line. As previously, the default comment-starter is ';', which can be changed by specifying the desired comment starter as the first argument to the filter creation sequence.<br />
<br />
The only option supported in this mode is <tt>-S</tt>, which enables the ''whitespace-must-follow mode'', in which a single space character (ASCII 20) is output after each comment sequence.<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Inline-comment&diff=529Inline-comment2023-10-16T13:24:36Z<p>Gray: </p>
<hr />
<div>== Introduction ==<br />
<br />
The <tt>inline-comment</tt> filter in [[MU_FILTER_DECODE|decode mode]] removes [http://en.wikipedia.org/wiki/Inline_comment inline comments] from the input stream. <br />
<br />
In [[MU_FILTER_ENCODE|encode mode]] it outputs a given byte sequence at the beginning of each output line.<br />
<br />
=== Decode mode ===<br />
<br />
In decode mode, the filter removes all lines beginning with a ''comment sequence'' from the input. The default comment sequence is <tt>;</tt> (a semicolon). The initialization of the <tt>inline-stream</tt> in this default mode is shown in the following example:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "inline-comment", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
To change the comment sequence supply the new sequence as the first argument. For example, the following filter will remove any lines starting with a <tt>rem</tt>:<br />
<br />
<syntaxhighlightlang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
char *argv[] = { "inline-comment", "rem", NULL },<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create_args (&flt, input, "inline-comment", 2, argv, MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
Notice that the above filter will remove any line starting with the <tt>rem</tt> characters, for example:<br />
<br />
<pre><br />
rem A comment.<br />
remark that should not be removed.<br />
</pre><br />
<br />
Removing of the second line seems wrong in most cases, therefore the filter supports a special ''whitespace-must-follow mode'', in which it recognizes the comment sequence only when it is immediatly followed by a whitespace character. This mode is enabled by the <br />
<tt>-S</tt> option to the filter. E.g.:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
char *argv[] = { "inline-comment", "rem", "-S", NULL },<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create_args (&flt, input, "inline-comment", 3, argv, MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
The following [[filter options|options]] modify the default behavior:<br />
<br />
; -i ''STR''<br />
: Emit line number information after each contiguous sequence of removed lines. ''STR'' supplies "information starter" -- a sequence of characters which is output before the actual line number.<br />
; -r <br />
: Remove empty lines, i.e. the ones that contain only whitespace characters.<br />
; -s<br />
: Squeeze whitespace. Each sequence of two or more whitespace characters encountered on input is replaced by a single space character on output.<br />
; -S <br />
: A ''whitespace-must-follow mode''. A comment sequence is recognized only if followed by a whitespace character. The character itself is retained on output. <br />
<br />
=== Encode mode ===<br />
<br />
In [[MU_FILTER_ENCODE|encode mode]] the ''inline-comment'' filter adds a comment-starter sequence at the beginning of each line. As previously, the default comment-starter is ';', which can be changed by specifying the desired comment starter as the first argument to the filter creation sequence.<br />
<br />
The only option supported in this mode is <tt>-S</tt>, which enables the ''whitespace-must-follow mode'', in which a single space character (ASCII 20) is output after each comment sequence.<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Iconv_(filter)&diff=528Iconv (filter)2023-10-16T13:23:55Z<p>Gray: </p>
<hr />
<div>The <tt>iconv</tt> [[filter]] converts between two charsets. It operates the same way in both [[MU_FILTER_DECODE|decode]] and [[MU_FILTER_ENCODE|encode]] modes. On initialization, it takes two mandatory arguments:<br />
<br />
* The name of the input charset<br />
* The name of the output charset<br />
<br />
Optional third argument specifies what to do when an illegal character sequence is encountered in the input stream. Its possible values are:<br />
<br />
; none<br />
: Return failure and stop further conversion.<br />
; copy-pass<br />
: Copy the offending octet to the output verbatim and continue conversion from the next octet.<br />
; copy-octal<br />
: Print the offending octet to the output using ''C'' octal conversion and continue conversion from the next octet.<br />
<br />
The default is <tt>copy-octal</tt> unless previously overridden by a call to [[mu_default_fallback_mode]] function.<br />
<br />
The following example creates a <tt>iconv</tt> filter for converting from [http://en.wikipedia.org/wiki/iso-8859-2 iso-8859-2] to [http://en.wikipedia.org/wiki/utf-8 utf-8], signalling an error on the first conversion error:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
char *argv[] = { "iconv", "iso-8859-2", "utf-8", "none", NULL };<br />
<br />
rc = mu_filter_chain_create (&flt, input, MU_FILTER_ENCODE, MU_STREAM_READ, 4, argv);<br />
</syntaxhighlight><br />
<br />
<br />
== See also ==<br />
<br />
* [[mu_default_fallback]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Htmlent&diff=527Htmlent2023-10-16T13:23:28Z<p>Gray: </p>
<hr />
<div>The <tt>htmlent</tt> filter converts characters '''<''', '''>''', and '''&''' to their corresponding [http://en.wikipedia.org/wiki/Character_entity_reference HTML entites] and vice-versa.<br />
<br />
In ''encode'' mode, the filter replaces each occurrence of these characters with the corresponding named entity. In ''decode'' mode the reverse operation is performed.<br />
<br />
The filter does not take arguments. <br />
<br />
The following object, declared in '''mailutils/filter.h''' describes the ''htmlent'' filter:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_htmlent_filter;<br />
</syntaxhighlight><br />
<br />
The example below shows how to create an instance of this filter in decode mode for reading:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "htmlent", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
<br />
== See also ==<br />
<br />
* [[xml (filter)|xml]] filter<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=From_(filter)&diff=526From (filter)2023-10-16T13:22:42Z<p>Gray: </p>
<hr />
<div>The <tt>from</tt> [[filter]] performs a traditional UNIX processing of lines starting with a <tt>From</tt> followed by a space character.<br />
<br />
; [[MU_FILTER_ENCODE|Encode]] mode<br />
: In encode mode, each "<tt>From </tt>" at the beginning of a line is replaced by "<tt>>From </tt>"<br />
; [[MU_FILTER_DECODE|Decode]] mode<br />
: In decode mode, the reverse operation is performed: initial ''greater-then'' sign (<tt>></tt>) is removed from any line starting with "<tt>>From </tt>".<br />
<br />
The following code creates an instance of read-only <tt>from</tt> stream which adds the ''greater-than'' character to each "<tt>>From </tt>" at the beginning of a line (the <tt>mu_stream_t input</tt> is supposed to have been initialized previously):<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
<br />
rc = mu_filter_create (&flt, input, "from", MU_FILTER_ENCODE, MU_STREAM_READ);<br />
</syntaxhighlight> <br />
<br />
The object describing this filter is declared in <tt>mailutils/filter.h</tt> as follows:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_from_filter;<br />
</syntaxhighlight><br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=DOT_(filter)&diff=525DOT (filter)2023-10-16T13:22:07Z<p>Gray: </p>
<hr />
<div>''DOT'' is a Mailutils [[filter]] useful for POP3 and SMTP I/O. In [[MU_FILTER_ENCODE|encode]] mode, it "[[byte-stuffing|byte-stuffs]]" the input by outputting an additional '.' in front of any '.' appearing at the beginning of a line. Upon closing the filter in this mode, it outputs additional ".\n".<br />
<br />
When [[MU_FILTER_DECODE|decoding]], the reverse is performed: additional dots are removed from beginning of lines. A single dot on a line by itself (i.e. the sequence "\n.\n") marks the end of the stream and causes the filter to return EOF. <br />
<br />
Mailutils also provides a hairy version of this filter, called [[CRLFDOT (filter)|CRLFDOT]], which combines its functionality with that of the [[CRLF (filter)|CRLF]] filter, i.e. performs the CRLF/LF translation in addition to byte-stuffing.<br />
<br />
The following object, declared in <tt>mailutils/filter.h</tt> describes the ''DOT'' filter:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_dot_filter;<br />
</syntaxhighlight><br />
<br />
This filter does not take arguments.<br />
<br />
The example below shows how to create a ''DOT'' filter instance in decode mode for reading:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "dot", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
== See also ==<br />
<br />
* [[CRLFDOT (filter)|CRLFDOT]]<br />
* [[CRLF (filter)|CRLF]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=C-escape&diff=524C-escape2023-10-16T13:21:15Z<p>Gray: </p>
<hr />
<div>The ''C-escape'' [[filter]] replaces C escape sequences with the corresponding control character and vice versa. <br />
<br />
In encode mode, recognized control characters are replaced with their C escapes. For example, newline (ASCII 10) becomes ''\n'', horizontal tab (ASCII 9) becomes ''\t'', etc.<br />
<br />
In decode mode, the reverse operation is performed, i.e. each C escape is replaced with the corresponding character. Unrecognized escape sequences are copied verbatim.<br />
<br />
Only named escapes are supported, i.e.: ''\\'', ''\a'', ''\b'', ''\f'', ''\n'', ''\r'', ''\t'', ''\v''.<br />
<br />
This filter does not take arguments. <br />
<br />
The following object, declared in mailutils/filter.h describes the ''C-escape'' filter:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_c_escape_filter;<br />
</syntaxhighlight><br />
<br />
The example below shows how to create an instance of this filter in decode mode for reading:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "C-escape", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Binary&diff=523Binary2023-10-16T13:20:43Z<p>Gray: </p>
<hr />
<div><tt>Binary</tt> is the simplest of Mailtils [[filter]]s. In both decode and encode modes, the filter copies its input to output verbatim.<br />
<br />
This filter is also available under the alias <tt>8bit</tt>.<br />
<br />
The <tt>binary</tt> filter takes no arguments.<br />
<br />
The following objects, declared in the header <tt>mailutils/filter.h</tt>, describe this filter:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_binary_filter;<br />
extern mu_filter_record_t mu_bit8_filter;<br />
</syntaxhighlight><br />
<br />
An example of how to create a binary filter stream:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "8bit", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Base64_(filter)&diff=522Base64 (filter)2023-10-16T13:20:08Z<p>Gray: </p>
<hr />
<div>The <tt>base64</tt> and <tt>B</tt> [[filter]]s encode or decode the input using the [http://en.wikipedia.org/wiki/Base64 base64] encoding.<br />
<br />
The only difference between the two filters is that <tt>base64</tt> in [[MU_FILTER_ENCODE|encode]] mode limits each ouput line length to 76 octets, whereas <tt>B</tt> produces a contiguous stream of base64 data.<br />
<br />
In [[MU_FILTER_DECODE|decode]] mode, both filters operate exactly the same way.<br />
<br />
These filters are described by the following objects (declared in <tt>mailutils/filter.h</tt>):<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_base64_filter;<br />
extern mu_filter_record_t mu_rfc_2047_B_filter;<br />
</syntaxhighlight><br />
<br />
The following example illustrates how to create a read-only filter for encoding the input stream in standard ''base64'' form, with output file length limited to 76 octets:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
<br />
rc = mu_filter_create (&flt, input, "base64", MU_FILTER_ENCODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
It is supposed that <tt>input</tt> is an object of type <tt>mu_stream_t</tt>, initialized previously.<br />
<br />
For the sake of completeness, the same effect can be achieved (with a slight loss in performance), by creating the following [[filter chain]]: <tt>"B + linelen 76"</tt>. This approach is illustrated in the example below:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
char *argv[] = { "B", "+", "linelen", "76", NULL };<br />
<br />
rc = mu_filter_chain_create (&flt, input, MU_FILTER_ENCODE, MU_STREAM_READ, 4, argv);<br />
</syntaxhighlight><br />
<br />
== See also ==<br />
<br />
* [[linelen]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=7bit&diff=5217bit2023-10-16T13:19:04Z<p>Gray: </p>
<hr />
<div>''Bin7'' is a Mailutils [[filter]]. It operates in both [[MU_FILTER_ENCODE|encode]] and [[MU_FILTER_DECODE|decode]] modes. <br />
<br />
In ''encode'' mode, the ''bin7'' filter converts its input into 7-bit ASCII, by clearing the 8th bit on each processed byte.<br />
<br />
In ''decode'' mode, it operates exactly as the [[8bit]] filter, i.e. copies its input to the output verbatim.<br />
<br />
This filter is described in <tt>mailutils/filter.h</tt>:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_bit7_filter;<br />
</syntaxhighlight><br />
<br />
To create this filter, use the [[mu_filter_stream_create]] function:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "bin7", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=CRLF_(filter)&diff=520CRLF (filter)2023-10-16T13:18:25Z<p>Gray: </p>
<hr />
<div>''CRLF'' is a Mailutils [[filter]] which converts line separators from LF (ASCII 10) to CRLF (ASCII 13 10) and vice-versa.<br />
<br />
In [[MU_FILTER_DECODE|decode]] mode, translates each CRLF sequence to LF. Takes no arguments.<br />
<br />
In [[MU_FILTER_ENCODE|encode]] mode, replaces each LF character with the CRLF sequence. If created with the <tt>-n</tt> option, the filter produces a "normalized" output, by preserving input CRLF untouched (by default they are translated to CR CR LF).<br />
<br />
The following object, declared in the header <tt>mailutils/filter.h</tt>, describes this filter:<br />
<br />
<syntaxhighlight lang="C"><br />
extern mu_filter_record_t mu_crlf_filter;<br />
</syntaxhighlight> <br />
<br />
The example below shows how to create a <tt>CRLF</tt> filter instance in decode mode for reading:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&stream);<br />
rc = mu_filter_create (&flt, input, "CRLF", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
This filter is also available under the name <tt>RFC822</tt>, which is deprecated.<br />
<br />
== See also ==<br />
* [[CRLFDOT (filter)|CRLFDOT]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Header_(filter)&diff=519Header (filter)2023-10-16T13:16:38Z<p>Gray: </p>
<hr />
<div>The <tt>header</tt> filter regards its input as a ''RFC-822'' email message. It extracts its header part (i.e. everything up to the first empty line) and copies it to the output. The body of the message is ignored. The filter operates only in [[MU_FILTER_DECODE|decode]] mode.<br />
<br />
An example of its usage:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&input);<br />
rc = mu_filter_create (&flt, input, "header", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</syntaxhighlight><br />
<br />
Input lines must be separated by single "\n" (LF) characters. If you want this filter to operate on CRLF-separated lines, [[filter chain|chain]] it with a [[CRLF]] filter, as shown in the example below:<br />
<br />
<syntaxhighlight lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
char *argv[] = { "CRLF", "+", "header", NULL };<br />
<br />
rc = mu_filter_chain_create (&flt, input, MU_FILTER_DECODE, MU_STREAM_READ, 3, argv);<br />
</syntaxhighlight><br />
<br />
== See also ==<br />
<br />
* [[CRLF (filter)|CRLF]]<br />
<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Vacation&diff=518Vacation2023-10-16T13:15:52Z<p>Gray: </p>
<hr />
<div>''Vacation'' is an E-mail autoresponder implemented as a [[Sieve]] extension action.<br />
<br />
== Syntax ==<br />
<br />
vacation [:days <''ndays'': number>]<br />
[:subject <''subject'': string>]<br />
[:aliases <''address-list'': list>]<br />
[:addresses <''noreply-address-list'': list>]<br />
[:reply_regex <''expr'': string>]<br />
[:reply_prefix <''prefix'': string>]<br />
[:sender <''addr'': email>]<br />
[:file]<br />
<''reply'': string><br />
<br />
''Vacation'' returns a message ''reply'' to the sender of the message being processed informing them that the recipient is currently not reading their mail. The message is sent to each sender once per reply interval specified by the ''ndays'' tagged parameter. The reply is formatted as a MIME message with ''reply_text'' as its body and ''subject'' as its <tt>Subject</tt> header. If <tt>:subject</tt> is not supplied, the <tt>Subject</tt> line is created by prefixing the subject of the original message with the<br />
''reply prefix'' ("<tt>Re: </tt>", by default). To avoid unnecessary duplication, this mechanism is suppressed if the original subject already begins with the reply prefix. <br />
<br />
If the tagged parameter <tt>:file</tt> is given, ''reply'' is treated as the name of a file from where to read the reply message. In this case, the file ''reply'' must contain an entire reply message (including headers) in RFC822 format. This message will be sent verbatim, except that its <tt>From</tt> and <tt>Subject</tt> headers will be modified. The <tt>From</tt> header will be set to email of the recipient of the original message. The <tt>Subject</tt> header will be modified as requested by the <tt>:subject</tt> tagged argument. <br />
<br />
The sender of the message is normally set to the recipient address of the original message. This behavior is changed by specifying the <tt>:sender</tt> argument. It is intended mainly for debugging.<br />
<br />
<br />
==Sample usage==<br />
<br />
<syntaxhighlight lang="C"><br />
require "vacation";<br />
<br />
vacation :days 7 :reply_regex "^(re|aw|sv|ang|odp|rv)(\[[0-9]+\])?:[[:blank:]]" text:<br />
I am not able to attend your mail now, because I am on vacation until 2010-07-01.<br />
I will reply to you when I am back.<br />
<br />
Best regards,<br />
Ty Coon<br />
.<br />
;<br />
</syntaxhighlight><br />
<br />
[[Category:Sieve]]<br />
[[Category:Sieve Actions]]<br />
[[Category:Sieve Extensions]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Debug_level&diff=517Debug level2023-10-16T13:14:51Z<p>Gray: </p>
<hr />
<div>__FORCETOC__<br />
== Introduction ==<br />
<br />
Mailutils debugging output is controlled by a set of levels, each of which can be set independently of others. Each debug level consists of a ''category name'', which identifies the part of Mailutils for which additional debugging is desired, and a level number, which tells Mailutils how verbose should its output be. <br />
<br />
Valid debug levels are:<br />
<br />
; error<br />
: Displays error conditions which are normally not reported, but passed to the caller layers for handling.<br />
; trace0 through trace9<br />
: Ten levels of verbosity, '''trace0''' producing less output, '''trace9''' producing the maximum amount of output.<br />
; prot<br />
: Display network protocol interaction, where applicable.<br />
<br />
Implementation and applicability of each level differs between various categories. The full list of categories is available in<br />
file <tt>libmailutils/diag/debcat</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/libmailutils/diag/debcat</ref> in the Mailutils source tree. Most useful categories and levels implemented for them are discussed later in this article.<br />
<br />
== Syntax ==<br />
<br />
Debug levels can be set either from the command line, by using the <tt>--debug-level</tt> option, or from the configuration file, <br />
via the [[configuration statement path|<tt>/debug/level</tt>]] statement. In both cases, it is specified as a list of individual levels, delimited with semicolons. Each individual level can be specified as:<br />
<br />
* <tt>!''category''</tt><br />
<br />
Disables all levels for the specified ''category''.<br />
<br />
* <tt>''category''</tt><br />
<br />
Enables all levels for the specified ''category''.<br />
<br />
* <tt>''category''.''level''</tt><br />
<br />
For this ''category'', enables all levels from <tt>error</tt> to ''level'', inclusive.<br />
<br />
* <tt>''category''.=''level''</tt><br />
<br />
Enables only the given ''level'' for this ''category''.<br />
<br />
* <tt>''category''.!''level''</tt><br />
<br />
Disables all levels from <tt>error</tt> to ''level'', inclusive, for this ''category''.<br />
<br />
* <tt>''category''.!=''level''</tt><br />
<br />
Disables only the given ''level'' for this ''category''.<br />
<br />
* <tt>''category''.''levelA''-''levelB''</tt><br />
<br />
Enable all levels in the range from ''levelA'' to ''levelB'', inclusive.<br />
<br />
* <tt>''category''.!''levelA''-''levelB''</tt><br />
<br />
Disable all levels in the range from ''levelA'' to ''levelB'', inclusive.<br />
<br />
Additionally, a comma-separated list of level specifications is allowed after the dot. For example, the following specification:<br />
<br />
<tt>acl.prot,!=trace9,!trace2</tt><br />
<br />
enables in category <tt>acl</tt> all levels, except <tt>trace9</tt>, <tt>trace0</tt>, <tt>trace1</tt>, and <tt>trace2</tt>.<br />
<br />
=== BNF ===<br />
<br />
The following specification in Backus-Naur form describes formally the Mailutils debug level:<br />
<br />
<syntaxhighlight lang="bnf"><br />
<debug-spec> ::= <level-spec> | <debug-level-list><br />
<debug-level-list> ::= <debug-level> | <debug-level-list> ";" <debug-level><br />
<debug-level> ::= <category> | "!" <category> |<br />
<category> "." <level-list><br />
<level-list> ::= <level-spec> | <level-list> "," <level-spec><br />
<level-spec> ::= <level> | <negate-level><br />
<negate-level> ::= "!" <level><br />
<level> ::= <level-number> | "=" <level-number> | <level-number> "-" <level-number><br />
<level-number> ::= "error" | "trace0" | "trace1" | "trace2" | "trace3" |<br />
"trace4" | "trace5" | "trace6" | "trace7" | "trace8" | "trace9" |<br />
"prot"<br />
</syntaxhighlight><br />
<br />
==Categories==<br />
<br />
===acl===<br />
<br />
This category enables debugging of [[Access Control Lists]]. Available levels are:<br />
<br />
;error<br />
:As usual, displays errors, not directly reported otherwise.<br />
;trace0<br />
:Basic tracing of ACL processing.<br />
;trace9<br />
:Traces the process of matching the ACL conditions.<br />
<br />
===config===<br />
<br />
This category affects configuration parser and/or lexical analyzer. The following levels are supported:<br />
<br />
;trace0<br />
:Minimal information about configuration statements.<br />
;trace2<br />
:Trace lexical structure of the configuration files.<br />
;trace7<br />
:Trace execution of the configuration parser.<br />
<br />
Due to its specific nature, this category cannot be enabled from the configuration file. A special hook is provided to facilitate debugging the configuration parser, namely, a [[pragmatic comment]] in form:<br />
<br />
<tt><br />
<nowiki>#debug=</nowiki>''debug-level-list''<br />
</tt><br />
<br />
causes ''debug-level-list'' to be parsed as described above. So, to force debugging of the configuration parser, one may add the following line at the very beginning of the configuration file:<br />
<br />
<tt><br />
<nowiki><br />
#debug=config.trace7<br />
</nowiki><br />
</tt><br />
<br />
===mailbox===<br />
<br />
Operations over mailboxes. This module supports the following levels: <tt>error</tt>, <tt>trace0</tt>, <tt>trace1</tt>, and <tt>prot</tt>. The latter is used by remote mailbox support libraries.<br />
<br />
===auth===<br />
<br />
Enables debugging information about authentication and authorization. This category supports the following levels: ''error'', ''trace0'', ''trace1'', and ''trace2''.<br />
<br />
In level ''trace0'', user data are reported along with the ''data source'' they were obtained from. The output may look like this:<br />
<br />
<tt><br />
<pre><br />
pop3d: source=system, name=gray, passwd=x, uid=120, gid=100, gecos=Sergey Poznyakoff, <br />
dir=/home/gray, shell=/bin/bash, mailbox=/var/mail/gray, quota=0, change_uid=1<br />
</pre><br />
</tt><br />
<br />
In the ''trace1'' level, additional flow traces are displayed.<br />
<br />
In the level ''trace2'', a detailed flow trace is displayed, which looks like:<br />
<br />
<tt><br />
<pre><br />
pop3d: Trying generic...<br />
pop3d: generic yields 38=Function not implemented<br />
pop3d: Trying system...<br />
pop3d: system yields 0=Success<br />
pop3d: Trying generic...<br />
pop3d: generic yields 4135=Authentication failed<br />
pop3d: Trying system...<br />
pop3d: system yields 0=Success<br />
</pre><br />
</tt><br />
<br />
===mailer===<br />
<br />
Debugs [[mailer]] operations. The following levels are supported: <br />
<br />
; error<br />
: Displays mild error conditions.<br />
; trace0<br />
: Traces mailer operations in general: displays what part of the message is being sent, etc.<br />
; trace6<br />
: When used together with <tt>prot</tt>, displays security-sensitive information (such as passwords, user keys, etc). in plaintext. By default, such information is replaced with asteriscs to reduce the possibility of the security compromise.<br />
; trace7<br />
: When used together with <tt>prot</tt>, displays the ''payload'' information as it is being sent. ''Payload'' is the actual message contents, i.e. the part of SMTP transaction that goes after the <tt>DATA</tt> command and which ends with a terminating dot line. Setting this level can generate huge amounts of information.<br />
; prot<br />
: For SMTP mailer: outputs transcripts of SMTP sessions.<br />
<br />
{{Note|Unless in a very secure environment, it is advised to avoid using level settings such as <tt>mailer.prot</tt> or <tt>mailer</tt> (without explicit level part), because the resulting output tends to be extremely copious and reveals sender private and security-sensitive data. If you wish to trace SMTP session flow, use <tt>mailer.<nowiki>=</nowiki>prot</tt> or at least <tt>mailer.prot,!trace6</tt>.}}<br />
<br />
===server===<br />
This category provides debugging information for Mailutils [[IP server]] objects. It supports the ''error'' and ''trace0'' levels.<br />
<br />
===folder===<br />
This category controls debugging information shown for operations related to Mailutils [[mu_folder_t|folder]]s.<br />
<br />
===remote===<br />
The <tt>remote</tt> category is used by <tt>imap4d</tt> and <tt>pop3d</tt> servers to request showing additional information in the session transcripts. This category takes effect only when the [[server transcript|transcript]] option is set. Valid levels are:<br />
<br />
; trace6<br />
: Show security-sensitive information (user passwords, etc.)<br />
; trace7<br />
: Show payload information<br />
<br />
==Notes==<br />
<references/><br />
<br />
[[Category:Debugging]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=514Main Page2023-05-01T12:29:07Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=f72870e913caae1b5a93d9881715ceac3af6ef37 version 3.16] is released on May 1, 2023. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.16.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=513Main Page2023-05-01T12:28:12Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=662fce4e78aa2f12641c9c27060dabd9741870a5 version 3.16] is released on May 1, 2023. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.16.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=512Main Page2022-04-17T19:18:17Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=9df491d77505ef8c07463eadc28a34df3159f2fb version 3.15] is released on April 17, 2022. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.15.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=511Main Page2022-04-17T19:15:51Z<p>Gray: New version</p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?id=9df491d77505ef8c07463eadc28a34df3159f2fb version 3.15] is released on April 17, 2022. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.15.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Mailutils-3&diff=510Mailutils-32022-01-02T09:15:48Z<p>Gray: New version</p>
<hr />
<div>The branch 3.X of GNU mailutils fixed the following deficiences found in versions 2.X:<br />
<br />
* Provide a consistent and effective interface for stream I/O.<br />
* Reorganize the codebase to use streams API, thereby improving performance.<br />
* Rewrite the filter API to improve its performance and to allow for easy creation and chaining of filters.<br />
* Improve logging and debugging support.<br />
* Provide API for word splitting and variable substitution instead of the obsolete <tt>argcv</tt> module.<br />
* Rewrite the client support for IMAP4.<br />
* Provide an extensive testsuite for Mailutils API as well as for the particular applications (in 2.X, the testcases were based on DejaGNU and were mostly non-portable).<br />
<br />
=== Releases ===<br />
<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.14.tar.gz Version 3.14], released on January 2, 2022<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.13.tar.gz Version 3.13], released on August 5, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.12.tar.gz Version 3.12], released on February 13, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.1.tar.gz Version 3.11.1], released on January 5, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.tar.gz Version 3.11], released on December 23, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.10.tar.gz Version 3.10], released on August 14, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.9.tar.gz Version 3.9], released on March 13, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.8.tar.gz Version 3.8], released on November 6, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.7.tar.gz Version 3.7], released on June 21, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.6.tar.gz Version 3.6], released on February 23, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.5.tar.gz Version 3.5], released on October 27, 2018<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.4.tar.gz Version 3.4], released on December 2, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.3.tar.gz Version 3.3], released on October 18, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.2.tar.gz Version 3.2], released on March 11, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.1.tar.gz Version 3.1.1], released on December 15, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.tar.gz Version 3.1], released on December 13, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.0.tar.gz Version 3.0], released on November 6, 2016, the first stable release<br />
* [http://alpha.gnu.org/gnu/mailutils/mailutils-2.99.94.tar.bz2 Version 2.99.94], released on November 6, 2011, the first alpha release of this branch.</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=509Main Page2022-01-02T09:14:30Z<p>Gray: New version</p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?id=2222572afa1d20482bbf70ea37941cb7c0f519c6 version 3.14] is released on January 2, 2022. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.14.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=508Main Page2021-08-05T11:43:35Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?id=c705c9c19feffbcd645927f6e1d4e7151c3f85ca version 3.13] is released on August 5, 2021. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.13.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=507Main Page2021-08-05T11:42:57Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?id=a07e985180b728d03c85f5660f0eca5d338dd7ee version 3.13] is released on August 5, 2021. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.13.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=506Main Page2021-08-05T11:42:17Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?id=85b25a7dc82d89561234779cc633a326cdc5ece8 version 3.13] is released on August 5, 2021. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.13.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Mailutils-3&diff=505Mailutils-32021-08-05T11:40:18Z<p>Gray: </p>
<hr />
<div>The branch 3.X of GNU mailutils fixed the following deficiences found in versions 2.X:<br />
<br />
* Provide a consistent and effective interface for stream I/O.<br />
* Reorganize the codebase to use streams API, thereby improving performance.<br />
* Rewrite the filter API to improve its performance and to allow for easy creation and chaining of filters.<br />
* Improve logging and debugging support.<br />
* Provide API for word splitting and variable substitution instead of the obsolete <tt>argcv</tt> module.<br />
* Rewrite the client support for IMAP4.<br />
* Provide an extensive testsuite for Mailutils API as well as for the particular applications (in 2.X, the testcases were based on DejaGNU and were mostly non-portable).<br />
<br />
=== Releases ===<br />
<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.13.tar.gz Version 3.13], released on August 5, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.12.tar.gz Version 3.12], released on February 13, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.1.tar.gz Version 3.11.1], released on January 5, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.tar.gz Version 3.11], released on December 23, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.10.tar.gz Version 3.10], released on August 14, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.9.tar.gz Version 3.9], released on March 13, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.8.tar.gz Version 3.8], released on November 6, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.7.tar.gz Version 3.7], released on June 21, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.6.tar.gz Version 3.6], released on February 23, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.5.tar.gz Version 3.5], released on October 27, 2018<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.4.tar.gz Version 3.4], released on December 2, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.3.tar.gz Version 3.3], released on October 18, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.2.tar.gz Version 3.2], released on March 11, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.1.tar.gz Version 3.1.1], released on December 15, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.tar.gz Version 3.1], released on December 13, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.0.tar.gz Version 3.0], released on November 6, 2016, the first stable release<br />
* [http://alpha.gnu.org/gnu/mailutils/mailutils-2.99.94.tar.bz2 Version 2.99.94], released on November 6, 2011, the first alpha release of this branch.</div>Grayhttps://mailutils.org/usqay/index.php?title=Mailutils-3&diff=504Mailutils-32021-02-13T12:42:32Z<p>Gray: </p>
<hr />
<div>The branch 3.X of GNU mailutils fixed the following deficiences found in versions 2.X:<br />
<br />
* Provide a consistent and effective interface for stream I/O.<br />
* Reorganize the codebase to use streams API, thereby improving performance.<br />
* Rewrite the filter API to improve its performance and to allow for easy creation and chaining of filters.<br />
* Improve logging and debugging support.<br />
* Provide API for word splitting and variable substitution instead of the obsolete <tt>argcv</tt> module.<br />
* Rewrite the client support for IMAP4.<br />
* Provide an extensive testsuite for Mailutils API as well as for the particular applications (in 2.X, the testcases were based on DejaGNU and were mostly non-portable).<br />
<br />
=== Releases ===<br />
<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.12.tar.gz Version 3.12], released on February 13, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.1.tar.gz Version 3.11.1], released on January 5, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.tar.gz Version 3.11], released on December 23, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.10.tar.gz Version 3.10], released on August 14, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.9.tar.gz Version 3.9], released on March 13, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.8.tar.gz Version 3.8], released on November 6, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.7.tar.gz Version 3.7], released on June 21, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.6.tar.gz Version 3.6], released on February 23, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.5.tar.gz Version 3.5], released on October 27, 2018<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.4.tar.gz Version 3.4], released on December 2, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.3.tar.gz Version 3.3], released on October 18, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.2.tar.gz Version 3.2], released on March 11, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.1.tar.gz Version 3.1.1], released on December 15, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.tar.gz Version 3.1], released on December 13, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.0.tar.gz Version 3.0], released on November 6, 2016, the first stable release<br />
* [http://alpha.gnu.org/gnu/mailutils/mailutils-2.99.94.tar.bz2 Version 2.99.94], released on November 6, 2011, the first alpha release of this branch.</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=503Main Page2021-02-13T12:39:48Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/tree/NEWS?id=50e2ce99915f828d4de548f570da3a4fa8fa56cb version 3.12] is released on February 13, 2021. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.12.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=502Main Page2021-01-05T14:11:12Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=1392e0e4a93a618582adeb7a9ccffb1ca2223b31 version 3.11.1] is released on January 5, 2021. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.11.1.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Mailutils-3&diff=501Mailutils-32021-01-05T14:09:18Z<p>Gray: </p>
<hr />
<div>The branch 3.X of GNU mailutils fixed the following deficiences found in versions 2.X:<br />
<br />
* Provide a consistent and effective interface for stream I/O.<br />
* Reorganize the codebase to use streams API, thereby improving performance.<br />
* Rewrite the filter API to improve its performance and to allow for easy creation and chaining of filters.<br />
* Improve logging and debugging support.<br />
* Provide API for word splitting and variable substitution instead of the obsolete <tt>argcv</tt> module.<br />
* Rewrite the client support for IMAP4.<br />
* Provide an extensive testsuite for Mailutils API as well as for the particular applications (in 2.X, the testcases were based on DejaGNU and were mostly non-portable).<br />
<br />
=== Releases ===<br />
<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.1.tar.gz Version 3.11.1], released on January 5, 2021<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.tar.gz Version 3.11], released on December 23, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.10.tar.gz Version 3.10], released on August 14, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.9.tar.gz Version 3.9], released on March 13, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.8.tar.gz Version 3.8], released on November 6, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.7.tar.gz Version 3.7], released on June 21, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.6.tar.gz Version 3.6], released on February 23, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.5.tar.gz Version 3.5], released on October 27, 2018<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.4.tar.gz Version 3.4], released on December 2, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.3.tar.gz Version 3.3], released on October 18, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.2.tar.gz Version 3.2], released on March 11, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.1.tar.gz Version 3.1.1], released on December 15, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.tar.gz Version 3.1], released on December 13, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.0.tar.gz Version 3.0], released on November 6, 2016, the first stable release<br />
* [http://alpha.gnu.org/gnu/mailutils/mailutils-2.99.94.tar.bz2 Version 2.99.94], released on November 6, 2011, the first alpha release of this branch.</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=500Main Page2020-12-23T14:27:28Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=c8f80734251804f25247fc3b3a234e990a217b57 version 3.11] is released on December 23, 2020. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.11.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Mailutils-3&diff=499Mailutils-32020-12-23T14:26:57Z<p>Gray: </p>
<hr />
<div>The branch 3.X of GNU mailutils fixed the following deficiences found in versions 2.X:<br />
<br />
* Provide a consistent and effective interface for stream I/O.<br />
* Reorganize the codebase to use streams API, thereby improving performance.<br />
* Rewrite the filter API to improve its performance and to allow for easy creation and chaining of filters.<br />
* Improve logging and debugging support.<br />
* Provide API for word splitting and variable substitution instead of the obsolete <tt>argcv</tt> module.<br />
* Rewrite the client support for IMAP4.<br />
* Provide an extensive testsuite for Mailutils API as well as for the particular applications (in 2.X, the testcases were based on DejaGNU and were mostly non-portable).<br />
<br />
=== Releases ===<br />
<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.11.tar.gz Version 3.11], released on December 23, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.10.tar.gz Version 3.10], released on August 14, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.9.tar.gz Version 3.9], released on March 13, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.8.tar.gz Version 3.8], released on November 6, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.7.tar.gz Version 3.7], released on June 21, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.6.tar.gz Version 3.6], released on February 23, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.5.tar.gz Version 3.5], released on October 27, 2018<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.4.tar.gz Version 3.4], released on December 2, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.3.tar.gz Version 3.3], released on October 18, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.2.tar.gz Version 3.2], released on March 11, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.1.tar.gz Version 3.1.1], released on December 15, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.tar.gz Version 3.1], released on December 13, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.0.tar.gz Version 3.0], released on November 6, 2016, the first stable release<br />
* [http://alpha.gnu.org/gnu/mailutils/mailutils-2.99.94.tar.bz2 Version 2.99.94], released on November 6, 2011, the first alpha release of this branch.</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=498Main Page2020-12-23T14:25:48Z<p>Gray: </p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=c8f80734251804f25247fc3b3a234e990a217b57 version 3.11] is released on November 23, 2020. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.11.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=Mu_c_streamftime&diff=497Mu c streamftime2020-11-27T11:37:42Z<p>Gray: </p>
<hr />
<div>{{DISPLAYTITLE:mu_c_streamftime}}<br />
== mu_c_streamftime ==<br />
<syntaxhighlight lang="C"><br />
#include <mailutils/datetime.h><br />
<br />
int mu_c_streamftime (mu_stream_t str, const char *fmt, struct tm *input_tm,<br />
struct mu_timezone *tz)<br />
</syntaxhighlight><br />
<br />
The function <tt>mu_c_streamftime</tt> formats the broken-down time <tt>tm</tt> with optional [[struct mu_timezone|timezone information]] <tt>tz</tt> according to the format specification <tt>format</tt> and writes the result to the stream <tt>str</tt>. If no timezone information is available, <tt>tz</tt> should be <tt>NULL</tt>. The function returns 0 on success and error code on error.<br />
<br />
The format string is similar to that of {{man|3|strftime}}. The function is designed to format timestamps for protocol exchange and therefore ignores locale settings (which is reflected by <tt>_c_</tt> in its name). A detailed description of the format string follows.<br />
<br />
=== Format string ===<br />
Ordinary characters placed in the format string are copied to the output stream without conversion. Conversion specifications are introduced by a <tt>%</tt> character, and terminated by a conversion specifier character. They are replaced in s as follows:<br />
<br />
;%a<br />
:The abbreviated weekday name.<br />
;%A<br />
:The full weekday name.<br />
;%b %h<br />
:The abbreviated month name.<br />
;%B<br />
:The full month name.<br />
;%c<br />
:Equivalent to <tt>"%a %b %e %H:%M:%S %Y"</tt>.<br />
;%C<br />
:The century number (year/100) as a 2-digit integer.<br />
;%d<br />
:The day of the month as a decimal number (range 01 to 31).<br />
;%D<br />
:Equivalent to <tt>"%m/%d/%y"</tt>.<br />
;%e<br />
:Like <tt>%d</tt>, the day of the month as a decimal number, but a leading zero is replaced by a space.<br />
;%E<br />
:A modifier. Actual conversion specifier must follow, e.g. <tt>%Ec</tt>. The Single Unix Specification mentions <tt>%Ec</tt>, <tt>%EC</tt>, <tt>%Ex</tt>, <tt>%EX</tt>, <tt>%Ey</tt>, and <tt>%EY</tt>, which are supposed to use a corresponding locale-dependent alternative representation. Since <tt>mu_c_streamftime</tt> explicitly operates in POSIX locale, this is a no-op.<br />
;%F<br />
:Equivalent to <tt>"%Y-%m-%d"</tt> (the ISO 8601 date format).<br />
;%G<br />
:The ISO 8601 year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see [[#Vspec|<tt>%V</tt>]] below). This has the same format and value as <tt>%y</tt>, except that if the ISO week number belongs to the previous or next year, that year is used instead.<br />
;%g<br />
:Like <tt>%G</tt>, but without century, that is, with a 2-digit year (00-99).<br />
;%H<br />
:The hour as a decimal number using a 24-hour clock (range 00 to 23).<br />
;%I<br />
:The hour as a decimal number using a 12-hour clock (range 01 to 12).<br />
;%j<br />
:The day of the year as a decimal number (range 001 to 366).<br />
;%k<br />
:The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank.<br />
;%l<br />
:The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. <br />
;%m<br />
:The month as a decimal number (range 01 to 12).<br />
;%M<br />
:The minute as a decimal number (range 00 to 59).<br />
;%n<br />
:A newline character.<br />
;%O<br />
:A no-op modifier. Actual conversion specifier must follow (The Single Unix Specification mentions <tt>%Od</tt>, <tt>%Oe</tt>, <tt>%OH</tt>, <tt>%OI</tt>, <tt>%Om</tt>, <tt>%OM</tt>, <tt>%OS</tt>, <tt>%Ou</tt>, <tt>%OU</tt>, <tt>%OV</tt>, <tt>%Ow</tt>, <tt>%OW</tt>, and <tt>%Oy</tt>, which are supposed to use alternative numeric symbols). <br />
;%p<br />
:Either "<tt>AM</tt>" or "<tt>PM</tt>" according to the given time value. Noon is treated as "<tt>PM</tt>" and midnight as "<tt>AM</tt>".<br />
;%P<br />
:Like <tt>%p</tt> but in lowercase: "<tt>am</tt>" or "<tt>pm</tt>".<br />
;%r<br />
:The time in a.m. or p.m. notation, i.e. equivalent to "<tt>%I:%M:%S %p</tt>".<br />
;%R<br />
:The time in 24-hour notation: <tt>%H:%M</tt><br />
;%s<br />
:The number of seconds since the Epoch.<br />
;%S<br />
:The second as a decimal number (range 00 to 60).<br />
;%t<br />
:A tab character.<br />
;%T<br />
:The time in 24-hour notation: "<tt>%H:%M:%S</tt>".<br />
;%u<br />
:The day of the week as a decimal, range 1 to 7, Monday being 1.<br />
;%U<br />
:The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01.<br />
<div id="Vspec"></div><br />
;%V<br />
:The ISO 8601:1988 week number of the current year as a decimal number range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week.;%w<br />
:The day of the week as a decimal, range 0 to 6, Sunday being 0.<br />
;%W<br />
:The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.<br />
;%x<br />
:The preferred date representation without the time: equivalent to "<tt>%D</tt>".<br />
;%X<br />
:The preferred date representation without the date: "<tt>%H:%M:%S</tt>".<br />
;%y<br />
:The year as a decimal number without a century (range 00 to 99).<br />
;%Y<br />
:The year as a decimal number including the century.<br />
;%Z<br />
:Same as <tt>%z</tt>. For [[mu_scan_datetime]]: Scan the following field as the timezone name or abbreviation. If not possible, scan it as "<tt>%z</tt>".<br />
;%z<br />
:The time-zone as hour offset from GMT.<br />
;%%<br />
:A literal '%' character.<br />
;%$<br />
:Ignored for compatibilty with [[mu_scan_datetime]].<br />
<br />
A percent sign followed by any character not listed above is written to the output stream verbatim.<br />
<br />
=== Examples ===<br />
<br />
<div id="MU_DATETIME_FROM"></div><br />
* UNIX mailbox from line:<br />
::"%a %b %e %H:%M:%S %Y"<br />
:It is available as <tt>MU_DATETIME_FROM</tt> macro, defined in <tt>mailutils/datetime.h</tt><br />
<div id="MU_DATETIME_FORM_RFC822"></div><br />
* RFC-822 date/time format:<br />
::"%a, %e %b %Y %H:%M:%S %z"<br />
:It is available as <tt>MU_DATETIME_FORM_RFC822</tt> macro.<br />
<div id="MU_DATETIME_IMAP"></div><br />
* IMAP INTERNALDATE format:<br />
::"%d-%b-%Y%$ %H:%M:%S %z"<br />
:It is available as <tt>MU_DATETIME_IMAP</tt> and <tt>MU_DATETIME_INTERNALDATE</tt> macros.<br />
<br />
== See also ==<br />
[[mu_strftime]], [[mu_scan_datetime]]<br />
<br />
[[Category:Date/Time Functions]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Mu_scan_datetime&diff=496Mu scan datetime2020-11-27T11:33:16Z<p>Gray: Document changes in endp semantics.</p>
<hr />
<div>{{DISPLAYTITLE:mu_scan_datetime}}<br />
<syntaxhighlight lang="C"><br />
#include <mailutils/datetime.h><br />
<br />
int mu_scan_datetime (const char *input, const char *format, struct tm *tm,<br />
struct mu_timezone *tz, char **endp);<br />
</syntaxhighlight><br />
<br />
The function <tt>mu_scan_datetime</tt> scans the string <tt>input</tt>, which is supposed to contain a date/time information, according to the <tt>format</tt> and places the resulting broken-down time in the <tt>tm</tt> variable. Unless <tt>tz</tt> is <tt>NULL</tt> the time zone information is stored there.<br />
<br />
On success, the function returns 0. If the input does not satisfy the format, <tt>MU_ERR_PARSE</tt> is returned. In both cases, unless <tt>endp</tt> is <tt>NULL</tt>, it will be initialized with the address of the character in <tt>input</tt> where the scanning stopped.<br />
<br />
If <tt>format</tt> itself is erroneous, <tt>MU_ERR_FORMAT</tt> is returned. The address of the character '''in fmt''' at which the error was detected will be stored in the memory location pointed to by <tt>endp</tt>,<br />
unless it is <tt>NULL</tt><ref>This change was introduced by commit [http://git.savannah.gnu.org/cgit/mailutils.git/commit/?id=df29254df82d4aa466f066dd76e00446e540e1cb df29254df8]. Prior to this, <tt>endp</tt> always received the address of the character in <tt>input</tt> where the conversion stopped.</ref>. Detailed information about the error is output to the [[Debug level|debugging channel]] <tt>mailbox.error</tt>.<br />
<br />
The <tt>format</tt> follows the [[mu_c_streamftime#Format_string|mu_c_streamftime format specification]] with several extensions. It is interpreted as follows:<br />
<br />
* A sequence of white-space characters (space, tab, newline, etc.; see [[mu_isspace]]) matches any amount of white space, including none, in the input.<br />
* An ordinary character (i.e., one other than white space or <tt>%</tt>) must exactly match the next character of input.<br />
* A [[mu_c_streamftime#Format_string|conversion specifier]] parses next characters according to its definition and stores the result in the corresponding location in <tt>tm</tt> or <tt>tz</tt> (unless the latter is <tt>NULL</tt>).<br />
* A '''flow control''' conversion alters the way the format is interpreted.<br />
<br />
Flow control specifiers are:<br />
<br />
;%?<br />
:This specifier matches any single character on input.<br />
<br />
;%\'''C'''<br />
:(where '''C''' is any single character) This specifier matches character '''C''' exactly. It is useful for specifying mandatory whitespace, as in:<br />
<br />
"%d-%b-%Y%\ %H:%M:%S %z"<br />
<br />
The above format requires date and time parts to be separated by a single space character.<br />
<br />
;%$<br />
:This specifier means optional end of input. That is, if the input does not match conversion past this specifier, it is not considered an error. Instead, the <tt>endp</tt> is set to the position where scanning stopped and 0 is returned. The <tt>tm</tt> and <tt>tz</tt> variables are left with the partial information collected so far.<br />
<br />
Consider, for example, date format used in IMAP SEARCH command. It is basically described as follows:<br />
<br />
"%d-%b-%Y %H:%M:%S %z"<br />
<br />
However, the time and timezone information is optional. To allow for that, the following format can be used instead:<br />
<br />
"%d-%b-%Y%$ %H:%M:%S %z"<br />
<br />
(see the <tt>MU_DATETIME_INTERNALDATE</tt> in <tt>mailutils/datetime.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/datetime.h</ref>).<br />
<br />
;%[ %| %]<br />
:The part of format enclosed between <tt>%[</tt> and <tt>%]</tt> specifiers is optional. The specifiers can be nested to any depth. The <tt>%|</tt> specifier appearing within the optional group introduces an '''optional alternative'''. Any number of alternatives may be present.<br />
<br />
Let's return to the above format for an example. It can be rewritten using optional group as follows:<br />
<br />
"%d-%b-%Y%[ %H:%M:%S %z%]"<br />
<br />
As a more complex example, consider RFC-822 date format. It has two optional parts: the day of week at the beginning and seconds at the end. The corresponding scan format is:<br />
<br />
"%[%a, %]%e %b %Y %H:%M%[:%S%] %z"<br />
<br />
See the <tt>MU_DATETIME_SCAN_RFC822</tt> define in <tt>mailutils/datetime.h</tt>.<br />
<br />
The following example illustrates nested optional groups:<br />
<br />
%[%a%[,%] %]%d %b %Y %H:%M:%S %z<br />
<br />
It matches any of the following date specifications:<br />
<br />
Tue, 03 May 2011 13:25:26 +0200<br />
Tue 03 May 2011 13:25:26 +0200<br />
03 May 2011 13:25:26 +0200<br />
<br />
;%( %| %)<br />
:Alternatives. This specifier requires that the input matches one of the alternatives separated by <tt>%|</tt>. Two or more alternatives may be specified, but at least two must be present. <br />
<br />
For example the following format<br />
<br />
"%a%(,%|:%|/%) %d %b %Y %H:%M:%S %z"<br />
<br />
requires the day of time (<tt>%a</tt>) to be followed by a single comma, semicolon or slash. Any other character following it will cause the format to fail.<br />
<br />
Optional blocks and alternative specifiers can be nested.<br />
<br />
==Notes==<br />
<references/><br />
<br />
== See also ==<br />
[[mu_c_streamftime]]<br />
<br />
[[Category:Date/Time Functions]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Mailutils-3&diff=495Mailutils-32020-08-15T20:44:10Z<p>Gray: </p>
<hr />
<div>The branch 3.X of GNU mailutils fixed the following deficiences found in versions 2.X:<br />
<br />
* Provide a consistent and effective interface for stream I/O.<br />
* Reorganize the codebase to use streams API, thereby improving performance.<br />
* Rewrite the filter API to improve its performance and to allow for easy creation and chaining of filters.<br />
* Improve logging and debugging support.<br />
* Provide API for word splitting and variable substitution instead of the obsolete <tt>argcv</tt> module.<br />
* Rewrite the client support for IMAP4.<br />
* Provide an extensive testsuite for Mailutils API as well as for the particular applications (in 2.X, the testcases were based on DejaGNU and were mostly non-portable).<br />
<br />
=== Releases ===<br />
<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.10.tar.gz Version 3.10], released on August 14, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.9.tar.gz Version 3.9], released on March 13, 2020<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.8.tar.gz Version 3.8], released on November 6, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.7.tar.gz Version 3.7], released on June 21, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.6.tar.gz Version 3.6], released on February 23, 2019<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.5.tar.gz Version 3.5], released on October 27, 2018<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.4.tar.gz Version 3.4], released on December 2, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.3.tar.gz Version 3.3], released on October 18, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.2.tar.gz Version 3.2], released on March 11, 2017<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.1.tar.gz Version 3.1.1], released on December 15, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.1.tar.gz Version 3.1], released on December 13, 2016<br />
* [http://ftp.gnu.org/gnu/mailutils/mailutils-3.0.tar.gz Version 3.0], released on November 6, 2016, the first stable release<br />
* [http://alpha.gnu.org/gnu/mailutils/mailutils-2.99.94.tar.bz2 Version 2.99.94], released on November 6, 2011, the first alpha release of this branch.</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=494Main Page2020-08-14T19:16:02Z<p>Gray: Announce version 3.10</p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=14c7654746d70bd3babc8164ad2336f5ceade426 version 3.10] is released on August 14, 2020. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.10.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=CRLF_(filter)&diff=493CRLF (filter)2020-07-09T10:22:12Z<p>Gray: </p>
<hr />
<div>''CRLF'' is a Mailutils [[filter]] which converts line separators from LF (ASCII 10) to CRLF (ASCII 13 10) and vice-versa.<br />
<br />
In [[MU_FILTER_DECODE|decode]] mode, translates each CRLF sequence to LF. Takes no arguments.<br />
<br />
In [[MU_FILTER_ENCODE|encode]] mode, replaces each LF character with the CRLF sequence. If created with the <tt>-n</tt> option, the filter produces a "normalized" output, by preserving input CRLF untouched (by default they are translated to CR CR LF).<br />
<br />
The following object, declared in the header <tt>mailutils/filter.h</tt>, describes this filter:<br />
<br />
<source lang="C"><br />
extern mu_filter_record_t mu_crlf_filter;<br />
</source> <br />
<br />
The example below shows how to create a <tt>CRLF</tt> filter instance in decode mode for reading:<br />
<br />
<source lang="C"><br />
int rc; /* Return code */<br />
mu_stream_t flt; /* Filter stream */<br />
mu_stream_t input; /* Input stream */<br />
<br />
initialize_input_stream (&stream);<br />
rc = mu_filter_create (&flt, input, "CRLF", MU_FILTER_DECODE, MU_STREAM_READ);<br />
</source><br />
<br />
This filter is also available under the name <tt>RFC822</tt>, which is deprecated.<br />
<br />
== See also ==<br />
* [[CRLFDOT (filter)|CRLFDOT]]<br />
<br />
[[Category:Filters]]<br />
[[Category:C API]]</div>Grayhttps://mailutils.org/usqay/index.php?title=Main_Page&diff=492Main Page2020-03-13T10:53:46Z<p>Gray: New release</p>
<hr />
<div>Mailutils Wiki documents the [[Mailutils-3|development version]] of [http://mailutils.org GNU Mailutils]. This is the primary source of information about Mailutils-3. Some of the material found here will be periodically collected, revised, recompiled and, if found suitable, incorporated into the Mailutils Manual, which is shipped with the project tarball. <br />
<br />
== NEWS ==<br />
<br />
* GNU mailutils [http://git.savannah.gnu.org/cgit/mailutils.git/plain/NEWS?id=7320f6a2fc84769f09c5b0278a7308bf0146bd64 version 3.9] is released on March 13, 2020. [https://ftp.gnu.org/gnu/mailutils/mailutils-3.9.tar.gz Click here] to download.<br />
<br />
== Mailutils Links ==<br />
* [http://savannah.gnu.org/projects/mailutils Development Site]<br />
* [http://puszcza.gnu.org.ua/projects/mailutils Its mirror]<br />
* [http://git.savannah.gnu.org/cgit/mailutils.git Git repository]<br />
* [http://savannah.gnu.org/git/?group=mailutils Instructions] on how to use it.<br />
* [http://git.gnu.org.ua/cgit/mailutils.git Mirror] repository.<br />
<br />
== Editing Hints ==<br />
* [http://www.mediawiki.org/wiki/Help:Contents User Help]<br />
* [http://www.mediawiki.org/wiki/Manual:FAQ Mediawiki FAQ]</div>Grayhttps://mailutils.org/usqay/index.php?title=File_Safety_Checks&diff=491File Safety Checks2019-11-06T13:12:13Z<p>Gray: /* The Forward File */</p>
<hr />
<div>== Introduction ==<br />
<br />
Some files used by GNU Mailutils keep confidential information and should be accessible for a limited set of system users. Before using such files, Mailutils applies to them a series of ''safety checks''. The file will be used only if all of the checks succeed. The number and purpose of these checks depend on the file being checked and can be configured.<br />
<br />
== Implemented Checks ==<br />
<div id="safety-checks"></div><br />
For the configuration purposes, each check has a symbolic name, which can be used to request or disable it.<br />
The table below lists all file safety checks implemented so far along with their names and descriptions. The checks are listed in the order of decreasing priority, which is also the order in which they are applied.<br />
<br />
;awrfil<br />
: Fails if the file is world-writable ('''a'''ll-'''wr'''itable '''fil'''e).).<br />
<br />
;gwrfil<br />
: Fails if the file is group-writable ('''g'''roup-'''wr'''itable '''fil'''e).<br />
<br />
;linkwrdir<br />
: Fails if the file is a symbolic link located in a (world- or group-) writable directory ('''Link'''ed file in '''wr'''itable '''dir'''ectory).<br />
<br />
;awrdir<br />
: Fails if the file is located in a world-writable directory ('''a'''ll-'''wr'''itable '''dir'''ectory).<br />
<br />
;gwrdir<br />
: Fails if the file is located in a group-writable directory ('''g'''roup-'''wr'''itable '''dir'''ectory).<br />
<br />
;ardfil<br />
: Fails if the file is world-readable ('''a'''ll-'''r'''ea'''d'''able '''fil'''e).<br />
<br />
;grdfil<br />
: Fails if the file is group-readable ('''g'''roup-'''r'''ea'''d'''able '''fil'''e).<br />
<br />
== Configuration ==<br />
<br />
Several configuration file keywords are provided to control safety checks applied to various files used by Mailutils. All of them take as their argument a white-space separated list of check names. Each check name, when listed, enables the corresponding check, unless preceded by a dash (''-'') which disables it. For symmetry, a name can be preceded by a plus sign, which does not alter its meaning. The checks specified this way alter the<br />
''default safety checks'' for that particular file. For example, consider the following specification:<br />
<br />
<code><br />
-grdfil -ardfil linkwrdir<br />
</code><br />
<br />
It relaxes the default set of checks by allowing the file to be group or world-readable, and tightens it<br />
on the other hand, by forbidding linked file in a writable directory.<br />
<br />
To facilitate configuration, the following special keywords are also provided:<br />
<br />
;all<br />
: Enables all the above checks.<br />
;none<br />
: Disables all checks.<br />
;default<br />
: Stands for a default check set for the file in question.<br />
<br />
Thus, to enable only '''ardfil''' and '''awrfil''' checks one would write:<br />
<br />
<code><br />
none +ardfil +awrfil<br />
</code><br />
<br />
== Checked Files ==<br />
<br />
This section discussed files to which the security checks are applied.<br />
<br />
=== SSL Files ===<br />
<br />
These are SSL key, certificate and certificate authority (CA) files. They are configured using <tt>tls-file-checks</tt><br />
block statement:<br />
<br />
<source><br />
tls-file-checks { <br />
key-file <arg: list>; # Configures safety checks for the key file.<br />
cert-file <arg: list>; # Configures safety checks for the certificate file.<br />
ca-file <arg: list>; # Configures safety checks for that file.<br />
};<br />
</source><br />
<br />
The keywords configuring file-specific tests and their corresponding defaults are as follows:<br />
<br />
;key-file<br />
: Safety checks for the SSL key file. The default is: <tt>all</tt>.<br />
<br />
;cert-file<br />
: Safety checks for the SSL certificate file. The default is: <tt>+awrfil +gwrfil +linkwrdir</tt>.<br />
<br />
;ca-file<br />
: Safety checks for the SSL certificate authority file. The default is: <tt>+awrfil +gwrfil +linkwrdir</tt>.<br />
<br />
For example, the following configuration allows the key file to be group-readable:<br />
<br />
<source><br />
tls-file-checks {<br />
ssl-key -grdfil;<br />
}<br />
</source><br />
<br />
=== The Forward File ===<br />
<br />
The '''forward''' file supported by [[mda]] and [[lmtpd]] is a traditional '''dot-forward''' file controlling mail forwarding for the system user. By default, the following checks are applied to it: <tt>awrfil gwrfil linkwrdir awrdir gwrdir</tt>. Additionally, the file is required to be owned by the user it belongs to. <br />
{{Note|That latter check should perhaps be configurable too, but currently there is no way to disable it.}}<br />
<br />
Safety checks for the forward file are controlled by the <tt>forward.file-checks</tt> statement. For example:<br />
<br />
<source><br />
forward {<br />
# Process forward file.<br />
file ".forward";<br />
# Configure safety checks for the forward file.<br />
file-checks default -gwrdir;<br />
}<br />
</source><br />
<br />
=== DBM Files ===<br />
<br />
Checks applied to various DBM files are controlled [[Database URL#param|individually]] for each database.<br />
<br />
== See also ==<br />
* [[File Safety Functions]]<br />
<br />
[[Category:Safety]]</div>Grayhttps://mailutils.org/usqay/index.php?title=File_Safety_Checks&diff=490File Safety Checks2019-11-06T13:09:06Z<p>Gray: /* The Forward File */</p>
<hr />
<div>== Introduction ==<br />
<br />
Some files used by GNU Mailutils keep confidential information and should be accessible for a limited set of system users. Before using such files, Mailutils applies to them a series of ''safety checks''. The file will be used only if all of the checks succeed. The number and purpose of these checks depend on the file being checked and can be configured.<br />
<br />
== Implemented Checks ==<br />
<div id="safety-checks"></div><br />
For the configuration purposes, each check has a symbolic name, which can be used to request or disable it.<br />
The table below lists all file safety checks implemented so far along with their names and descriptions. The checks are listed in the order of decreasing priority, which is also the order in which they are applied.<br />
<br />
;awrfil<br />
: Fails if the file is world-writable ('''a'''ll-'''wr'''itable '''fil'''e).).<br />
<br />
;gwrfil<br />
: Fails if the file is group-writable ('''g'''roup-'''wr'''itable '''fil'''e).<br />
<br />
;linkwrdir<br />
: Fails if the file is a symbolic link located in a (world- or group-) writable directory ('''Link'''ed file in '''wr'''itable '''dir'''ectory).<br />
<br />
;awrdir<br />
: Fails if the file is located in a world-writable directory ('''a'''ll-'''wr'''itable '''dir'''ectory).<br />
<br />
;gwrdir<br />
: Fails if the file is located in a group-writable directory ('''g'''roup-'''wr'''itable '''dir'''ectory).<br />
<br />
;ardfil<br />
: Fails if the file is world-readable ('''a'''ll-'''r'''ea'''d'''able '''fil'''e).<br />
<br />
;grdfil<br />
: Fails if the file is group-readable ('''g'''roup-'''r'''ea'''d'''able '''fil'''e).<br />
<br />
== Configuration ==<br />
<br />
Several configuration file keywords are provided to control safety checks applied to various files used by Mailutils. All of them take as their argument a white-space separated list of check names. Each check name, when listed, enables the corresponding check, unless preceded by a dash (''-'') which disables it. For symmetry, a name can be preceded by a plus sign, which does not alter its meaning. The checks specified this way alter the<br />
''default safety checks'' for that particular file. For example, consider the following specification:<br />
<br />
<code><br />
-grdfil -ardfil linkwrdir<br />
</code><br />
<br />
It relaxes the default set of checks by allowing the file to be group or world-readable, and tightens it<br />
on the other hand, by forbidding linked file in a writable directory.<br />
<br />
To facilitate configuration, the following special keywords are also provided:<br />
<br />
;all<br />
: Enables all the above checks.<br />
;none<br />
: Disables all checks.<br />
;default<br />
: Stands for a default check set for the file in question.<br />
<br />
Thus, to enable only '''ardfil''' and '''awrfil''' checks one would write:<br />
<br />
<code><br />
none +ardfil +awrfil<br />
</code><br />
<br />
== Checked Files ==<br />
<br />
This section discussed files to which the security checks are applied.<br />
<br />
=== SSL Files ===<br />
<br />
These are SSL key, certificate and certificate authority (CA) files. They are configured using <tt>tls-file-checks</tt><br />
block statement:<br />
<br />
<source><br />
tls-file-checks { <br />
key-file <arg: list>; # Configures safety checks for the key file.<br />
cert-file <arg: list>; # Configures safety checks for the certificate file.<br />
ca-file <arg: list>; # Configures safety checks for that file.<br />
};<br />
</source><br />
<br />
The keywords configuring file-specific tests and their corresponding defaults are as follows:<br />
<br />
;key-file<br />
: Safety checks for the SSL key file. The default is: <tt>all</tt>.<br />
<br />
;cert-file<br />
: Safety checks for the SSL certificate file. The default is: <tt>+awrfil +gwrfil +linkwrdir</tt>.<br />
<br />
;ca-file<br />
: Safety checks for the SSL certificate authority file. The default is: <tt>+awrfil +gwrfil +linkwrdir</tt>.<br />
<br />
For example, the following configuration allows the key file to be group-readable:<br />
<br />
<source><br />
tls-file-checks {<br />
ssl-key -grdfil;<br />
}<br />
</source><br />
<br />
=== The Forward File ===<br />
<br />
The '''forward''' file supported by [[mda]] and [[lmtpd]] is a traditional '''dot-forward''' file controlling mail forwarding for the system user. By default, the following checks are applied to it: <tt>awrfil gwrfil linkwrdir awrdir gwrdir</tt>. Additionally, the file is required to be owned by the user it belongs to. <br />
{{Note|That latter check should perhaps be configurable too, but currently there is no way to disable it.}}<br />
<br />
Safety checks for the forward file are controlled by the <tt>forward-file-checks</tt> statement. For example:<br />
<br />
<source><br />
forward-file-checks default -gwrdir;<br />
</source><br />
<br />
=== DBM Files ===<br />
<br />
Checks applied to various DBM files are controlled [[Database URL#param|individually]] for each database.<br />
<br />
== See also ==<br />
* [[File Safety Functions]]<br />
<br />
[[Category:Safety]]</div>Gray