* $Id: README,v 1.1 2003/11/24 15:34:38 lwa Exp $ * What is it ? libmdq is a library is a quota managment library for Maildir++ soft quota system. On the system, a cache file with the current amount of space used is keeped in the maildir. Time to time the cache file is recomputed. * API Tutorial Include mdq.h file in your programs : #include If you want to count trashed message, set mdq_trash_quota = 1; note that you shall do this in all of your programs. If you want display diagnotics message, define mdq_error, for example, to get diagnotics to standart standart error, define a function like this : #include #include my_mdq_error(const char *format, va_list args) { vprintf(stderr, format, args); } then set it to mdq_error mdq_error = my_mdq_error; If you plan to add message in the maildir, get user quota information, for example : quotastr = "10000S"; which mean that mailbox is limited to 10 Kb of total messages. If you plan to only remove message, you can use a NULL quota description string. Then open the quota description structure. MDQ *q = mdq_open(".", quotastr); No need to check return value. On error mdq_open() will return NULL and NULL is a quota description pointer with no limits. To check if Maildir is not over quota : if (mdq_test(q, 0, 0) == 0) { ... } to check if Maildir can recieve a message of 1000 bytes : if (mdq_test(q, 1000, 1) == 0) { ... } mdq_test() would return -1 is theyre is no space left. After you have removed a message of 1000 bytes, tell it to the quota system: mdq_add(q, -1000, -1); After you have added a message of 1000 bytes, do it so: mdq_add(q, 1000, 1); You may also add or remove messages by packets with a single mdq_add() call: mdq_add(q, -3000, -3); /* 3 messages of 3000 bytes total removed */ When you finished the Maildir message edition, mdq_close(q); This will flush data on disk if needed and close any opened ressources. The soft quota system is designed to use no lock. This mean informations may be wrong sometime, specialy when theyre is two or more maildir writers. To limit this effect when maildir is overquota, the quota total will be recomputed within 15 minuts. To avoid false information within long time, you shall not use persistent MDQ*. mdq_close() openned resources as soon as possible.