notmuch(3)
💖 NAME 💖
okay so welcome to notmuch(3), the Library Functions Manual bestie for the notmuch library. notmuch is The notmuch API — literally that. The iconic tagline? "Not much of an email library, (just index and search)." periodt. 🎀
🧾 SYNOPSIS 🧾
This is the top-of-page vibe check: the macros, typedefs, and enumerations that make up the notmuch API surface. Keep the names, values, and spellings exactly as they are — no creative edits, bestie. 💅
✨ Macros ✨
LIBNOTMUCH_CHECK_VERSION(major, minor, micro)— checks the version of the notmuch library you're compiling against. Compile-time compatibility check, iykyk. Exact declaration:
#define LIBNOTMUCH_CHECK_VERSION(major, minor, micro)NOTMUCH_TAG_MAX— the longest possible tag value. This is the tag-length ceiling, fr fr. Exact declaration:
#define NOTMUCH_TAG_MAX 200🦋 Typedefs 🦋
notmuch_bool_t— the notmuch boolean type. Exact typedef:
typedef int notmuch_bool_tnotmuch_compact_status_cb_t— a callback invoked bynotmuch_database_compactto notify the user of the progress of the compaction process. Exact typedef:
typedef void(* notmuch_compact_status_cb_t) (const char *message, void *closure)👑 Enumerations 👑
These enums are the status codes, modes, sort values, flags, config keys, and crypto-policy choices. All values stay exactly as written. 🌈
notmuch_status_t— status codes used for the return values of most functions. If a call has something to say, this is how it says it. Exact enum:
enum notmuch_status_t { NOTMUCH_STATUS_SUCCESS = 0,
NOTMUCH_STATUS_OUT_OF_MEMORY, NOTMUCH_STATUS_READ_ONLY_DATABASE,
NOTMUCH_STATUS_XAPIAN_EXCEPTION, NOTMUCH_STATUS_FILE_ERROR,
NOTMUCH_STATUS_FILE_NOT_EMAIL, NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID,
NOTMUCH_STATUS_NULL_POINTER, NOTMUCH_STATUS_TAG_TOO_LONG,
NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
NOTMUCH_STATUS_UNBALANCED_ATOMIC,
NOTMUCH_STATUS_UNSUPPORTED_OPERATION,
NOTMUCH_STATUS_UPGRADE_REQUIRED, NOTMUCH_STATUS_PATH_ERROR,
NOTMUCH_STATUS_IGNORED, NOTMUCH_STATUS_ILLEGAL_ARGUMENT,
NOTMUCH_STATUS_MALFORMED_CRYPTO_PROTOCOL,
NOTMUCH_STATUS_FAILED_CRYPTO_CONTEXT_CREATION,
NOTMUCH_STATUS_UNKNOWN_CRYPTO_PROTOCOL, NOTMUCH_STATUS_NO_CONFIG,
NOTMUCH_STATUS_NO_DATABASE, NOTMUCH_STATUS_DATABASE_EXISTS,
NOTMUCH_STATUS_BAD_QUERY_SYNTAX, NOTMUCH_STATUS_NO_MAIL_ROOT,
NOTMUCH_STATUS_CLOSED_DATABASE, NOTMUCH_STATUS_ITERATOR_EXHAUSTED,
NOTMUCH_STATUS_OPERATION_INVALIDATED, NOTMUCH_STATUS_LAST_STATUS }notmuch_database_mode_t— database open mode fornotmuch_database_open. Exact enum:
enum notmuch_database_mode_t { NOTMUCH_DATABASE_MODE_READ_ONLY = 0,
NOTMUCH_DATABASE_MODE_READ_WRITE }notmuch_query_syntax_t— query syntax enum. The original gives these values and no extra description, so here they are, untouched. Exact enum:
enum notmuch_query_syntax_t { NOTMUCH_QUERY_SYNTAX_XAPIAN,
NOTMUCH_QUERY_SYNTAX_SEXP }notmuch_sort_t— sort values fornotmuch_query_set_sort. Exact enum:
enum notmuch_sort_t { NOTMUCH_SORT_OLDEST_FIRST,
NOTMUCH_SORT_NEWEST_FIRST, NOTMUCH_SORT_MESSAGE_ID,
NOTMUCH_SORT_UNSORTED }notmuch_exclude_t— exclude values fornotmuch_query_set_omit_excluded. Exact enum:
enum notmuch_exclude_t { NOTMUCH_EXCLUDE_FLAG, NOTMUCH_EXCLUDE_TRUE,
NOTMUCH_EXCLUDE_FALSE, NOTMUCH_EXCLUDE_ALL }notmuch_message_flag_t— message flags. Exact enum:
enum notmuch_message_flag_t { NOTMUCH_MESSAGE_FLAG_MATCH,
NOTMUCH_MESSAGE_FLAG_EXCLUDED, NOTMUCH_MESSAGE_FLAG_GHOST }notmuch_config_key_t— configuration keys known to libnotmuch. Exact enum:
enum notmuch_config_key_t { NOTMUCH_CONFIG_FIRST,
NOTMUCH_CONFIG_DATABASE_PATH = NOTMUCH_CONFIG_FIRST,
NOTMUCH_CONFIG_MAIL_ROOT, NOTMUCH_CONFIG_HOOK_DIR,
NOTMUCH_CONFIG_BACKUP_DIR, NOTMUCH_CONFIG_EXCLUDE_TAGS,
NOTMUCH_CONFIG_NEW_TAGS, NOTMUCH_CONFIG_NEW_IGNORE,
NOTMUCH_CONFIG_SYNC_MAILDIR_FLAGS, NOTMUCH_CONFIG_PRIMARY_EMAIL,
NOTMUCH_CONFIG_OTHER_EMAIL, NOTMUCH_CONFIG_USER_NAME,
NOTMUCH_CONFIG_AUTOCOMMIT, NOTMUCH_CONFIG_EXTRA_HEADERS,
NOTMUCH_CONFIG_INDEX_AS_TEXT, NOTMUCH_CONFIG_AUTHORS_SEPARATOR,
NOTMUCH_CONFIG_AUTHORS_MATCHED_SEPARATOR, NOTMUCH_CONFIG_LAST }notmuch_decryption_policy_t— stating a policy about how to decrypt messages. Exact enum:
enum notmuch_decryption_policy_t { NOTMUCH_DECRYPT_FALSE,
NOTMUCH_DECRYPT_TRUE, NOTMUCH_DECRYPT_AUTO, NOTMUCH_DECRYPT_NOSTASH
}✨ Functions ✨
Okay bestie, this is the motherlode — every single function in the C API, in order, nothing skipped. Buckle up, hydrate, and let's go 💖
const char * notmuch_status_to_string (notmuch_status_t status)— hands you a string version of anotmuch_status_tvalue. So when something returns a status code you can actually read it like a human instead of squinting at an int 💅notmuch_status_t notmuch_database_create (const char *path, notmuch_database_t **database)— creates a brand-new, empty notmuch database living at path. Fresh start energy ✨notmuch_status_t notmuch_database_create_verbose (const char *path, notmuch_database_t **database, char **error_message)— literallynotmuch_database_create, except it optionally hands back an error message too. Same vibe, more receipts 🫶notmuch_status_t notmuch_database_open (const char *path, notmuch_database_mode_t mode, notmuch_database_t **database)— deprecated alias fornotmuch_database_open_with_configwithconfig_path="anderror_message=NULL. It's giving "still works, but go use the new one" 🙈notmuch_status_t notmuch_database_open_verbose (const char *path, notmuch_database_mode_t mode, notmuch_database_t **database, char **error_message)— deprecated alias fornotmuch_database_open_with_configwithconfig_path=". Same deal, move along, nothing new here 💀notmuch_status_t notmuch_database_open_with_config (const char *database_path, notmuch_database_mode_t mode, const char *config_path, const char *profile, notmuch_database_t **database, char **error_message)— opens an existing notmuch database at database_path, pulling its configuration from config_path. The main character of openers 👑notmuch_status_t notmuch_database_load_config (const char *database_path, const char *config_path, const char *profile, notmuch_database_t **database, char **error_message)— loads configuration from the config file, the database, and/or the defaults. A little bit of everything, a pick-and-mix 🍓notmuch_status_t notmuch_database_create_with_config (const char *database_path, const char *config_path, const char *profile, notmuch_database_t **database, char **error_message)— creates a new notmuch database at database_path, using the configuration in config_path. Creation, but make it config-aware ✨const char * notmuch_database_status_string (const notmuch_database_t *notmuch)— retrieves the last status string for the given database. The receipts from last time 📜notmuch_status_t notmuch_database_close (notmuch_database_t *database)— commits changes and closes the given notmuch database. Say bye, but save your work first 💾notmuch_status_t notmuch_database_compact (const char *path, const char *backup_path, notmuch_compact_status_cb_t status_cb, void *closure)— compacts a notmuch database, backing the original up to the given backup_path. Glow-up for your db, with a safety copy 🎀notmuch_status_t notmuch_database_compact_db (notmuch_database_t *database, const char *backup_path, notmuch_compact_status_cb_t status_cb, void *closure)— just likenotmuch_database_compact, but it takes an already-open database as its parameter instead of a path 🦋notmuch_status_t notmuch_database_destroy (notmuch_database_t *database)— destroys the notmuch database, closing it if that's still necessary, and frees all the associated resources. Cleanup queen — free everything, leave no crumbs 🌸const char * notmuch_database_get_path (notmuch_database_t *database)— returns the database path of the given database. Where does it live? Right here 📍unsigned int notmuch_database_get_version (notmuch_database_t *database)— returns the database format version of the given database. Version check, but for the db 🧚notmuch_bool_t notmuch_database_needs_upgrade (notmuch_database_t *database)— can the database be upgraded to a newer database version? A yes/no vibe check on whether it's time 💅notmuch_status_t notmuch_database_upgrade (notmuch_database_t *database, void(*progress_notify)(void *closure, double progress), void *closure)— upgrades the current database to the latest supported version. You even get aprogress_notifycallback so you can watch the progress happen — obsessed 🔥notmuch_status_t notmuch_database_begin_atomic (notmuch_database_t *notmuch)— begins an atomic database operation. All-or-nothing, iykyk ⭐notmuch_status_t notmuch_database_end_atomic (notmuch_database_t *notmuch)— signals the end of an atomic database operation. Bookend to the one above 🫶unsigned long notmuch_database_get_revision (notmuch_database_t *notmuch, const char **uuid)— returns the committed database revision and the UUID. Two-for-one, we love to see it 👑notmuch_status_t notmuch_database_get_directory (notmuch_database_t *database, const char *path, notmuch_directory_t **directory)— retrieves a directory object from the database for path. Directory era 📁notmuch_status_t notmuch_database_index_file (notmuch_database_t *database, const char *filename, notmuch_indexopts_t *indexopts, notmuch_message_t **message)— adds a message file to a database and indexes it so future searches can actually find it. This is the whole point of the thing, no cap 🔍notmuch_status_t notmuch_database_add_message (notmuch_database_t *database, const char *filename, notmuch_message_t **message)— deprecated alias fornotmuch_database_index_filecalled withNULLindexopts. The old faithful, on its way out 🙈notmuch_status_t notmuch_database_remove_message (notmuch_database_t *database, const char *filename)— removes a message filename from the given notmuch database. Exit, stage left 💀notmuch_status_t notmuch_database_find_message (notmuch_database_t *database, const char *message_id, notmuch_message_t **message)— finds a message with the given message_id. ID in, message out 💌notmuch_status_t notmuch_database_find_message_by_filename (notmuch_database_t *notmuch, const char *filename, notmuch_message_t **message)— finds a message with the given filename. Same hunt, different clue 🕵️notmuch_tags_t * notmuch_database_get_all_tags (notmuch_database_t *db)— returns a list of every tag found in the database. All the tags, every last one 💅notmuch_status_t notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode)— reopens an already-open notmuch database. Close the loop, reopen the vibe 🔁
✨ Query era ✨
notmuch_query_t * notmuch_query_create (notmuch_database_t *database, const char *query_string)— creates a new query for database. Your search starts here 🎀notmuch_status_t notmuch_query_create_with_syntax (notmuch_database_t *database, const char *query_string, notmuch_query_syntax_t syntax, notmuch_query_t **output)— the source page gives this one no little description at all, bestie. Iconic mysterious behaviour, but that's genuinely all it says 💀const char * notmuch_query_get_query_string (const notmuch_query_t *query)— returns thequery_stringof this query. What did we even search for? Here's the receipt 📜notmuch_database_t * notmuch_query_get_database (const notmuch_query_t *query)— returns the notmuch database of this query. Every query knows where it came from 🫶void notmuch_query_set_omit_excluded (notmuch_query_t *query, notmuch_exclude_t omit_excluded)— says whether to omit excluded results entirely or simply flag them. Your call, babe 💅void notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort)— specifies the sorting you want for this query. Aesthetic order matters ✨notmuch_sort_t notmuch_query_get_sort (const notmuch_query_t *query)— returns the sort specified for this query. What order are we in again? 🌸notmuch_status_t notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag)— adds a tag that'll be excluded from the query results by default. Not invited to the party 🚫notmuch_status_t notmuch_query_search_threads (notmuch_query_t *query, notmuch_threads_t **out)— executes a query for threads and returns anotmuch_threads_tobject you can use to iterate over the results. Threads, iterated, immaculate 🧵notmuch_status_t notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out)— deprecated alias fornotmuch_query_search_threads. The_stera is cooked 🙈notmuch_status_t notmuch_query_search_messages (notmuch_query_t *query, notmuch_messages_t **out)— executes a query for messages and returns anotmuch_messages_tobject you can iterate over. Same energy, message flavoured ✉️notmuch_status_t notmuch_query_search_messages_st (notmuch_query_t *query, notmuch_messages_t **out)— deprecated alias fornotmuch_query_search_messages. Bye bestie 👋void notmuch_query_destroy (notmuch_query_t *query)— destroys anotmuch_query_talong with any associated resources. Clean up after yourself, always 🎀
✨ Iterating threads ✨
notmuch_bool_t notmuch_threads_valid (notmuch_threads_t *threads)— is the given threads iterator pointing at a valid thread? Yes/no, vibe check ✅notmuch_status_t notmuch_threads_status (notmuch_threads_t *threads)— gets the status of the given threads iterator. How's it doing? 💫notmuch_thread_t * notmuch_threads_get (notmuch_threads_t *threads)— gets the current thread from threads as anotmuch_thread_t. Grab it 🫳void notmuch_threads_move_to_next (notmuch_threads_t *threads)— moves the threads iterator to the next thread. Next 💅void notmuch_threads_destroy (notmuch_threads_t *threads)— destroys anotmuch_threads_tobject. Free it and go 🌈
✨ Counting things ✨
notmuch_status_t notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count)— returns the number of messages matching a search. Numbers, but make it mail 🔢notmuch_status_t notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count)— deprecated alias fornotmuch_query_count_messages. The_stcurse strikes again 💀notmuch_status_t notmuch_query_count_threads (notmuch_query_t *query, unsigned *count)— returns the number of threads matching a search. Thread tally, slay 🧵notmuch_status_t notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count)— deprecated alias fornotmuch_query_count_threads. Same old story 🙈
✨ All about a thread ✨
const char * notmuch_thread_get_thread_id (notmuch_thread_t *thread)— gets the thread ID of thread. Its name tag 💖int notmuch_thread_get_total_messages (notmuch_thread_t *thread)— gets the total number of messages in thread. The whole count 🍓int notmuch_thread_get_total_files (notmuch_thread_t *thread)— gets the total number of files in thread. Files counted too, we don't forget 🗂️notmuch_messages_t * notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread)— gets anotmuch_messages_titerator for the top-level messages in thread, in oldest-first order. Top level only, and the oldest goes first ⏳notmuch_messages_t * notmuch_thread_get_messages (notmuch_thread_t *thread)— gets anotmuch_thread_titerator for all the messages in thread, in oldest-first order. (Yep, that's genuinely what the page says —notmuch_thread_titerator, that's the wording, not me ✨) All the messages, oldest-first 🌸int notmuch_thread_get_matched_messages (notmuch_thread_t *thread)— gets the number of messages in thread that matched the search. Only the ones that made the cut 💅const char * notmuch_thread_get_authors (notmuch_thread_t *thread)— gets the authors of thread as a UTF-8 string. Who's in the group chat 👥const char * notmuch_thread_get_subject (notmuch_thread_t *thread)— gets the subject of thread as a UTF-8 string. The subject line, decoded and gorgeous 🎀time_t notmuch_thread_get_oldest_date (notmuch_thread_t *thread)— gets the date of the oldest message in thread as atime_tvalue. Ancient history ⏰time_t notmuch_thread_get_newest_date (notmuch_thread_t *thread)— gets the date of the newest message in thread as atime_tvalue. Fresh off the wire ✨notmuch_tags_t * notmuch_thread_get_tags (notmuch_thread_t *thread)— gets the tags for thread, returning anotmuch_tags_tobject you can use to iterate over all of them. Tag haul 🏷️void notmuch_thread_destroy (notmuch_thread_t *thread)— destroys anotmuch_thread_tobject. Release the thread 🦋
✨ Iterating messages ✨
notmuch_bool_t notmuch_messages_valid (notmuch_messages_t *messages)— is the given messages iterator pointing at a valid message? Another vibe check ✅notmuch_status_t notmuch_messages_status (notmuch_messages_t *messages)— gets the status of the given messages iterator. Status report incoming 📋notmuch_message_t * notmuch_messages_get (notmuch_messages_t *messages)— gets the current message from messages as anotmuch_message_t. Grab the message 🫳void notmuch_messages_move_to_next (notmuch_messages_t *messages)— moves the messages iterator to the next message. Onward 💫void notmuch_messages_destroy (notmuch_messages_t *messages)— bestie, when you're done with anotmuch_messages_tobject, this is the lil cleanup crew that destroys it. bye bye memory leak 👋notmuch_tags_t * notmuch_messages_collect_tags (notmuch_messages_t *messages)— scoops up a list of tags from all the messages, like collecting every sticker from every notebook and putting them in one pile ✨notmuch_database_t * notmuch_message_get_database (const notmuch_message_t *message)— hands you the database that this message is living in 🏠const char * notmuch_message_get_message_id (notmuch_message_t *message)— the message ID of message, served fresh 💌const char * notmuch_message_get_thread_id (notmuch_message_t *message)— the thread ID of message, so you know which convo it belongs to 🧵notmuch_messages_t * notmuch_message_get_replies (notmuch_message_t *message)— gives you anotmuch_messages_titerator over all the replies to message. the whole group chat under one text, basically 💬int notmuch_message_count_files (notmuch_message_t *message)— how many files are associated with a message, total. yes it counts for you, we love a math moment 🔢const char * notmuch_message_get_filename (notmuch_message_t *message)— gets a filename for the email matching message (just one, not the whole set) 📁notmuch_filenames_t * notmuch_message_get_filenames (notmuch_message_t *message)— and this one gets all the filenames for the email matching message. the full collection 🗂️notmuch_status_t notmuch_message_reindex (notmuch_message_t *message, notmuch_indexopts_t *indexopts)— re-indexes the e-mail for message using the index options you supply. glow-up era for that message 🔄notmuch_bool_t notmuch_message_get_flag (notmuch_message_t *message, notmuch_message_flag_t flag)— peeks at the value of a flag for the email matching message 🚩notmuch_status_t notmuch_message_get_flag_st (notmuch_message_t *message, notmuch_message_flag_t flag, notmuch_bool_t *is_set)— same mission, flag value for the email matching message, but status-flavoured 🚩✨void notmuch_message_set_flag (notmuch_message_t *message, notmuch_message_flag_t flag, notmuch_bool_t value)— sets a flag value for the email matching message. you pick the flag, you pick the value 💅time_t notmuch_message_get_date (notmuch_message_t *message)— the date of message as atime_tvalue. timestamped 🕰️const char * notmuch_message_get_header (notmuch_message_t *message, const char *header)— grabs the value of whichever header you asked for from message, returned as a UTF-8 string 🎀notmuch_tags_t * notmuch_message_get_tags (notmuch_message_t *message)— the tags for message, handed back as anotmuch_tags_tobject that you can iterate over to see all of them 🏷️notmuch_status_t notmuch_message_add_tag (notmuch_message_t *message, const char *tag)— slaps a tag onto the given message 👑notmuch_status_t notmuch_message_remove_tag (notmuch_message_t *message, const char *tag)— takes that tag back off the given message. we're un-labeling 💔notmuch_status_t notmuch_message_remove_all_tags (notmuch_message_t *message)— nukes every tag from the given message. clean slate, no cap 🧹notmuch_status_t notmuch_message_maildir_flags_to_tags (notmuch_message_t *message)— adds/removes tags based on the maildir flags sitting in the message's filename(s) 🔁notmuch_bool_t notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag)— returnsTRUEif any filename of message has maildir flag flag, andFALSEotherwise ✅notmuch_status_t notmuch_message_has_maildir_flag_st (notmuch_message_t *message, char flag, notmuch_bool_t *is_set)— checks the message for maildir flag flag, status-style 🕵️notmuch_status_t notmuch_message_tags_to_maildir_flags (notmuch_message_t *message)— renames the message filename(s) so the tags get encoded as maildir flags. tags → filenames, the remix 🔀notmuch_status_t notmuch_message_freeze (notmuch_message_t *message)— freezes the current state of message inside the database ❄️notmuch_status_t notmuch_message_thaw (notmuch_message_t *message)— thaws the frozen message, syncing up any changes that happened while it was frozen into the notmuch database 🌊void notmuch_message_destroy (notmuch_message_t *message)— destroys anotmuch_message_tobject. bye bestie 🫶
notmuch_bool_t notmuch_tags_valid (notmuch_tags_t *tags)— is this tags iterator pointing at a valid tag? yes/no moment 🤔const char * notmuch_tags_get (notmuch_tags_t *tags)— the current tag from tags, as a string 💖void notmuch_tags_move_to_next (notmuch_tags_t *tags)— nudges the tags iterator along to the next tag ➡️void notmuch_tags_destroy (notmuch_tags_t *tags)— destroys anotmuch_tags_tobject ✨
notmuch_status_t notmuch_directory_set_mtime (notmuch_directory_t *directory, time_t mtime)— stores an mtime in the database for directory 🕰️time_t notmuch_directory_get_mtime (notmuch_directory_t *directory)— gets the mtime of a directory, as previously stored withnotmuch_directory_set_mtime. look at us, remembering things 💭notmuch_filenames_t * notmuch_directory_get_child_files (notmuch_directory_t *directory)— anotmuch_filenames_titerator listing all the filenames of messages in the database inside the given directory 📂notmuch_filenames_t * notmuch_directory_get_child_directories (notmuch_directory_t *directory)— same energy, but it lists all the filenames of sub-directories in the database inside the given directory 🌳notmuch_status_t notmuch_directory_delete (notmuch_directory_t *directory)— deletes the directory document from the database and destroys thenotmuch_directory_tobject. two birds, one slay 💅void notmuch_directory_destroy (notmuch_directory_t *directory)— destroys anotmuch_directory_tobject 🎀
notmuch_bool_t notmuch_filenames_valid (notmuch_filenames_t *filenames)— is the filenames iterator pointing at a valid filename? vibe check 🦋const char * notmuch_filenames_get (notmuch_filenames_t *filenames)— the current filename from filenames, as a string 📄void notmuch_filenames_move_to_next (notmuch_filenames_t *filenames)— moves the filenames iterator to the next filename ➡️void notmuch_filenames_destroy (notmuch_filenames_t *filenames)— destroys anotmuch_filenames_tobject ⭐
notmuch_status_t notmuch_database_set_config (notmuch_database_t *db, const char *key, const char *value)— sets config key to value ⚙️notmuch_status_t notmuch_database_get_config (notmuch_database_t *db, const char *key, char **value)— retrieves config item key and assigns it to value 📥notmuch_status_t notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix, notmuch_config_list_t **out)— creates an iterator for all config items whose keys match a given prefix 🗃️notmuch_bool_t notmuch_config_list_valid (notmuch_config_list_t *config_list)— is the config_list iterator valid (i.e. ...and yeah, the original literally drops off mid-sentence there, bestie 😭 that's just how the page is, I'm not making up the rest)const char * notmuch_config_list_key (notmuch_config_list_t *config_list)— returns the key for the current config pair 🔑const char * notmuch_config_list_value (notmuch_config_list_t *config_list)— returns the value for the current config pair 💫void notmuch_config_list_move_to_next (notmuch_config_list_t *config_list)— moves the config_list iterator to the next pair ➡️void notmuch_config_list_destroy (notmuch_config_list_t *config_list)— frees any resources held by config_list 🧹
const char * notmuch_config_get (notmuch_database_t *notmuch, notmuch_config_key_t key)— gets a configuration value from an open database 🔍notmuch_status_t notmuch_config_set (notmuch_database_t *notmuch, notmuch_config_key_t key, const char *val)— sets a configuration value in an open database ✍️notmuch_config_values_t * notmuch_config_get_values (notmuch_database_t *notmuch, notmuch_config_key_t key)— returns an iterator for a';'-delimited list of configuration values 📜notmuch_config_values_t * notmuch_config_get_values_string (notmuch_database_t *notmuch, const char *key)— same thing, iterator for a';'-delimited list of configuration values, but you pass the key as a string 🧵notmuch_bool_t notmuch_config_values_valid (notmuch_config_values_t *values)— is the given config_values iterator pointing at a valid element? 👀const char * notmuch_config_values_get (notmuch_config_values_t *values)— gets the current value from the values iterator 💖void notmuch_config_values_move_to_next (notmuch_config_values_t *values)— moves the values iterator to the next element ➡️void notmuch_config_values_start (notmuch_config_values_t *values)— resets the values iterator back to the first element. rewind time ⏪void notmuch_config_values_destroy (notmuch_config_values_t *values)— destroys a config values iterator, along with any associated resources 🫶
notmuch_config_pairs_t * notmuch_config_get_pairs (notmuch_database_t *notmuch, const char *prefix)— returns an iterator for (key, value) configuration pairs 🎟️notmuch_bool_t notmuch_config_pairs_valid (notmuch_config_pairs_t *pairs)— is the given config_pairs iterator pointing at a valid element? ✅void notmuch_config_pairs_move_to_next (notmuch_config_pairs_t *pairs)— moves the config_pairs iterator to the next element ➡️const char * notmuch_config_pairs_key (notmuch_config_pairs_t *pairs)— gets the current key from the config_pairs iterator 🔑const char * notmuch_config_pairs_value (notmuch_config_pairs_t *pairs)— gets the current value from the config_pairs iterator 💎void notmuch_config_pairs_destroy (notmuch_config_pairs_t *pairs)— destroys a config_pairs iterator, along with any associated resources 🧚
notmuch_status_t notmuch_config_get_bool (notmuch_database_t *notmuch, notmuch_config_key_t key, notmuch_bool_t *val)— gets a configuration value from an open database, but as a Boolean. true/false girlie 💅const char * notmuch_config_path (notmuch_database_t *notmuch)— returns the path of the config file that got loaded, if any 📍
notmuch_indexopts_t * notmuch_database_get_default_indexopts (notmuch_database_t *db)— gets the current default indexing options for a given database ⚙️notmuch_status_t notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts, notmuch_decryption_policy_t decrypt_policy)— specifies whether to decrypt encrypted parts while indexing 🔐notmuch_decryption_policy_t notmuch_indexopts_get_decrypt_policy (const notmuch_indexopts_t *indexopts)— returns whether to decrypt encrypted parts while indexing 🔓void notmuch_indexopts_destroy (notmuch_indexopts_t *options)— destroys anotmuch_indexopts_tobject 🌸
notmuch_bool_t notmuch_built_with (const char *name)— interrogates the library about its compile-time features. putting it under the spotlight 🎤
🏷️ Message Properties 💫
Okay so this interface is the whole ~attach arbitrary (key,value) string pairs to a message~ situation — it lets you add those pairs, remove them, and iterate over them. like lil sticky notes on a message, iykyk 🗒️
⚠️ heads up bestie: the caller should take some care as to what keys they add or delete values for, because other subsystems or extensions may depend on these properties. not me casually breaking someone else's extension 🙈
Also, bestie, pls see notmuch-properties(7) for more details about specific properties and the conventions around their use. 💖
typedef struct _notmuch_string_map_iterator notmuch_message_properties_t— opaque message property iterator. It’s giving “mystery box you can walk through,” iykyk. ✨notmuch_status_t notmuch_message_get_property (notmuch_message_t *message, const char *key, const char **value)— retrieve the value for a single propertykey. Simple, clean, iconic.notmuch_status_t notmuch_message_add_property (notmuch_message_t *message, const char *key, const char *value)— add a(key,value)pair to a message. Slay.notmuch_status_t notmuch_message_remove_property (notmuch_message_t *message, const char *key, const char *value)— remove a(key,value)pair from a message. Bye bestie 👋notmuch_status_t notmuch_message_remove_all_properties (notmuch_message_t *message, const char *key)— remove all(key,value)pairs from the given message. Full reset energy.notmuch_status_t notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, const char *prefix)— remove all(prefix*,value)pairs from the given message. Prefix-coded cleanup 💅notmuch_message_properties_t * notmuch_message_get_properties (notmuch_message_t *message, const char *key, notmuch_bool_t exact)— get the properties formessage, returning anotmuch_message_properties_tobject which can be used to iterate over all properties.notmuch_status_t notmuch_message_count_properties (notmuch_message_t *message, const char *key, unsigned int *count)— return the number of properties namedkeybelonging to the specific message.notmuch_bool_t notmuch_message_properties_valid (notmuch_message_properties_t *properties)— is the given properties iterator pointing at a valid(key,value)pair?void notmuch_message_properties_move_to_next (notmuch_message_properties_t *properties)— move the properties iterator to the next(key,value)pair.const char * notmuch_message_properties_key (notmuch_message_properties_t *properties)— return the key from the current(key,value)pair.const char * notmuch_message_properties_value (notmuch_message_properties_t *properties)— return the value from the current(key,value)pair.void notmuch_message_properties_destroy (notmuch_message_properties_t *properties)— destroy anotmuch_message_properties_tobject. Clean up after yourself, bestie 🫶
✨ Detailed Description ✨
Not much of an email library, (just index and search). That’s the whole vibe, no cap. 💀
🌸 Macro Definition Documentation 🌸
#define LIBNOTMUCH_CHECK_VERSION( major, minor, micro)
Value:
(LIBNOTMUCH_MAJOR_VERSION > (major) || \
(LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION > (minor)) || \
(LIBNOTMUCH_MAJOR_VERSION == (major) && LIBNOTMUCH_MINOR_VERSION == (minor) && \
LIBNOTMUCH_MICRO_VERSION >= (micro)))Check the version of the notmuch library being compiled against. Return true if the library being compiled against is of the specified version or above. For example:
#if LIBNOTMUCH_CHECK_VERSION(3, 1, 0)
(code requiring libnotmuch 3.1.0 or above)
#endifLIBNOTMUCH_CHECK_VERSION has been defined since version 3.1.0; to check for versions prior to that, use:
#if !defined(NOTMUCH_CHECK_VERSION)
(code requiring libnotmuch prior to 3.1.0)
#endif🦋 Enumeration Type Documentation 🦋
enum notmuch_status_t
Status codes used for the return values of most functions. A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function completed without error. Any other value indicates an error.
The lineup 💅:
NOTMUCH_STATUS_SUCCESS— no error occurred.NOTMUCH_STATUS_OUT_OF_MEMORY— out of memory.NOTMUCH_STATUS_READ_ONLY_DATABASE— an attempt was made to write to a database opened in read-only mode.NOTMUCH_STATUS_XAPIAN_EXCEPTION— a Xapian exception occurred.NOTMUCH_STATUS_FILE_ERROR— an error occurred trying to read or write to a file (this could be file not found, permission denied, etc.).NOTMUCH_STATUS_FILE_NOT_EMAIL— a file was presented that doesn’t appear to be an email message.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID— a file contains a message ID that is identical to a message already in the database.NOTMUCH_STATUS_NULL_POINTER— the user erroneously passed aNULLpointer to a notmuch function.NOTMUCH_STATUS_TAG_TOO_LONG— a tag value is too long (exceedsNOTMUCH_TAG_MAX).NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW— thenotmuch_message_thawfunction has been called more times thannotmuch_message_freeze.NOTMUCH_STATUS_UNBALANCED_ATOMIC—notmuch_database_end_atomichas been called more times thannotmuch_database_begin_atomic.NOTMUCH_STATUS_UNSUPPORTED_OPERATION— the operation is not supported.NOTMUCH_STATUS_UPGRADE_REQUIRED— the operation requires a database upgrade.NOTMUCH_STATUS_PATH_ERROR— there is a problem with the proposed path, e.g. a relative path passed to a function expecting an absolute path.NOTMUCH_STATUS_IGNORED— the requested operation was ignored. Depending on the function, this may not be an actual error.NOTMUCH_STATUS_ILLEGAL_ARGUMENT— one of the arguments violates the preconditions for the function, in a way not covered by a more specific argument.NOTMUCH_STATUS_MALFORMED_CRYPTO_PROTOCOL— a MIME object claimed to have cryptographic protection which notmuch tried to handle, but the protocol was not specified in an intelligible way.NOTMUCH_STATUS_FAILED_CRYPTO_CONTEXT_CREATION— notmuch attempted to do crypto processing, but could not initialize the engine needed to do so.NOTMUCH_STATUS_UNKNOWN_CRYPTO_PROTOCOL— a MIME object claimed to have cryptographic protection, and notmuch attempted to process it, but the specific protocol was something that notmuch doesn’t know how to handle.NOTMUCH_STATUS_NO_CONFIG— unable to load a config file.NOTMUCH_STATUS_NO_DATABASE— unable to load a database.NOTMUCH_STATUS_DATABASE_EXISTS— database exists, so not (re)-created.NOTMUCH_STATUS_BAD_QUERY_SYNTAX— syntax error in query.NOTMUCH_STATUS_NO_MAIL_ROOT— no mail root could be deduced from parameters and environment.NOTMUCH_STATUS_CLOSED_DATABASE— database is not fully opened, or has been closed.NOTMUCH_STATUS_ITERATOR_EXHAUSTED— the iterator being examined has been exhausted and contains no more items.NOTMUCH_STATUS_OPERATION_INVALIDATED— an operation that was being performed on the database has been invalidated while in progress, and must be re-executed. This will typically happen while iterating over query results and the underlying Xapian database is modified by another process so that the currently open version cannot be read anymore.NOTMUCH_STATUS_LAST_STATUS— not an actual status value. Just a way to find out how many valid status values there are.
enum notmuch_database_mode_t
Database open mode for notmuch_database_open.
NOTMUCH_DATABASE_MODE_READ_ONLY— open database for reading only.NOTMUCH_DATABASE_MODE_READ_WRITE— open database for reading and writing.
enum notmuch_sort_t
Sort values for notmuch_query_set_sort.
NOTMUCH_SORT_OLDEST_FIRST— oldest first.NOTMUCH_SORT_NEWEST_FIRST— newest first.NOTMUCH_SORT_MESSAGE_ID— sort by message-id.NOTMUCH_SORT_UNSORTED— do not sort.
enum notmuch_exclude_t
Exclude values for notmuch_query_set_omit_excluded. The strange order is to maintain backward compatibility: the old FALSE/TRUE options correspond to the new NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
enum notmuch_decryption_policy_t
Stating a policy about how to decrypt messages. See index.decrypt in notmuch-config(1) for more details.
💅 Function Documentation 💅
const char * notmuch_status_to_string (notmuch_status_t status)
Get a string representation of a notmuch_status_t value. The result is read-only. Cute and to the point.
notmuch_status_t notmuch_database_create (const char * path, notmuch_database_t ** database)
Create a new, empty notmuch database located at path. The path should be a top-level directory to a collection of plain-text email messages (one message per file). This call will create a new .notmuch directory within path where notmuch will store its data.
After a successful call to notmuch_database_create, the returned database will be open so the caller should call notmuch_database_destroy when finished with it.
The database will not yet have any data in it (notmuch_database_create itself is a very cheap function). Messages contained within path can be added to the database by calling notmuch_database_index_file.
In case of any failure, this function returns an error status and sets *database to NULL (after printing an error message on stderr).
Return value 💖:
NOTMUCH_STATUS_SUCCESS: successfully created the database.NOTMUCH_STATUS_NULL_POINTER: the givenpathargument isNULL.NOTMUCH_STATUS_OUT_OF_MEMORY: out of memory.NOTMUCH_STATUS_PATH_ERROR: filename is too long.NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to create the database file (such as permission denied, or file not found, etc.), or the database already exists.NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred.
notmuch_status_t notmuch_database_create_verbose (const char * path, notmuch_database_t ** database, char ** error_message)
Like notmuch_database_create, except optionally return an error message. This message is allocated by malloc and should be freed by the caller. Very “you break it, you bought it” but make it C.
notmuch_status_t notmuch_database_open (const char * path, notmuch_database_mode_t mode, notmuch_database_t ** database)
Deprecated alias for notmuch_database_open_with_config with config_path="" and error_message=NULL.
⚠️ Deprecated: deprecated as of libnotmuch 5.4 (notmuch 0.32).
notmuch_status_t notmuch_database_open_verbose (const char * path, notmuch_database_mode_t mode, notmuch_database_t ** database, char ** error_message)
Deprecated alias for notmuch_database_open_with_config with config_path="".
⚠️ Deprecated: deprecated as of libnotmuch 5.4 (notmuch 0.32).
notmuch_status_t notmuch_database_open_with_config (const char * database_path, notmuch_database_mode_t mode, const char * config_path, const char * profile, notmuch_database_t ** database, char ** error_message)
Open an existing notmuch database located at database_path, using configuration in config_path.
Parameters
database_path— path to existing database.
...so, continuing the argument deets from where we left off 💖:
database_path— a notmuch database is literally just a Xapian database holding the appropriate metadata 🗂️. It should've been created at some point in the past (not necessarily by this process, ngl) by callingnotmuch_database_create.
If database_path is NULL, then we use the location specified:
- in the environment variable
NOTMUCH_DATABASE, if it's non-empty - in a configuration file, located as described under
config_path - by
$XDG_DATA_HOME/notmuch/$PROFILE, whereXDG_DATA_HOMEdefaults to"$HOME/.local/share"andPROFILEis as discussed inprofile
If database_path is non-NULL but doesn't look like a Xapian database, bestie, we check for a directory .notmuch/xapian below database_path — that's the behavior of notmuch_database_open_verbose pre-0.32, iykyk 😌.
mode— the mode to open the database. Use one ofNOTMUCH_DATABASE_MODE_READ_WRITEorNOTMUCH_DATABASE_MODE_READ_ONLY.config_path— path to the config file. The config file is key-value, with mandatory sections. Seenotmuch-config(5)for more info. The key-value pair overrides the corresponding configuration data stored in the database (seenotmuch_database_get_config) 👑
If config_path is NULL, use the path specified:
- in environment variable
NOTMUCH_CONFIG, if non-empty - by
XDG_CONFIG_HOME/notmuch/, whereXDG_CONFIG_HOMEdefaults to"$HOME/.config" - by
$HOME/.notmuch-config
If config_path is "" (empty string), then do not open any configuration file. periodt.
profile— name of the profile (the configuration/database variant). If it's non-NULL, append it to the directory / file path determined forconfig_pathanddatabase_path🌸.
If NULL, then use:
- environment variable
NOTMUCH_PROFILEif defined - otherwise
"default"for directories and""(empty string) for paths
database— pointer to the database object. May not beNULL, no cap. The caller should callnotmuch_database_destroywhen finished with this database 🫶.
In case of any failure, this function returns an error status and sets *database to NULL.
error_message— if non-NULL, store the error message from opening the database. Any such message is allocated bymalloc(3)and should be freed by the caller (yes, you, bestie — free it 💀).
Return values
NOTMUCH_STATUS_SUCCESS— successfully opened the database ✨NOTMUCH_STATUS_NULL_POINTER— the givendatabaseargument isNULLNOTMUCH_STATUS_NO_CONFIG— no config file was found. Fatal. 😭NOTMUCH_STATUS_OUT_OF_MEMORY— out of memoryNOTMUCH_STATUS_FILE_ERROR— an error occurred trying to open the database or config file (like permission denied, or file not found, etc.), or the database version is unknownNOTMUCH_STATUS_XAPIAN_EXCEPTION— a Xapian exception occurred
Since
libnotmuch 5.4 (notmuch 0.32)
notmuch_status_t notmuch_database_load_config (const char * database_path, const char * config_path, const char * profile, notmuch_database_t ** database, char ** error_message)
Loads configuration from config file, database, and/or defaults 💅. For a description of the arguments:
See also — notmuch_database_open_with_config
For errors other than NO_DATABASE and NO_CONFIG, *database is set to NULL.
Return values
NOTMUCH_STATUS_SUCCESS— successfully loaded configuration ✨NOTMUCH_STATUS_NO_CONFIG— no config file was loaded. Not fatal.NOTMUCH_STATUS_NO_DATABASE— no config information was loaded from a database. Not fatal.NOTMUCH_STATUS_OUT_OF_MEMORY— out of memoryNOTMUCH_STATUS_FILE_ERROR— an error occurred trying to open the database or config file (such as permission denied, or file not found, etc.)NOTMUCH_STATUS_XAPIAN_EXCEPTION— a Xapian exception occurred
Since
libnotmuch 5.4 (notmuch 0.32)
notmuch_status_t notmuch_database_create_with_config (const char * database_path, const char * config_path, const char * profile, notmuch_database_t ** database, char ** error_message)
Creates a shiny new notmuch database located at database_path, using the configuration in config_path 🦋. For a description of the arguments:
See also — notmuch_database_open_with_config
In case of any failure, this function returns an error status and sets *database to NULL.
Return values
NOTMUCH_STATUS_SUCCESS— successfully created the database 🎀NOTMUCH_STATUS_DATABASE_EXISTS— the database already exists, so it wasn't createdNOTMUCH_STATUS_OUT_OF_MEMORY— out of memoryNOTMUCH_STATUS_FILE_ERROR— an error occurred trying to open the database or config file (such as permission denied, or file not found, etc.)NOTMUCH_STATUS_XAPIAN_EXCEPTION— a Xapian exception occurred
Since
libnotmuch 5.4 (notmuch 0.32)
notmuch_status_t notmuch_database_close (notmuch_database_t * database)
Commits changes and closes the given notmuch database 🔥. After notmuch_database_close has been called, calls to other functions on objects derived from this database may either behave as if the database had not been closed (e.g., if the required data has been cached) or may fail with a NOTMUCH_STATUS_XAPIAN_EXCEPTION. The only further operation permitted on the database itself is to call notmuch_database_destroy, and that's the tea ☕.
notmuch_database_close can be called multiple times. Later calls have no effect.
For writable databases, notmuch_database_close commits all changes to disk before closing the database — unless the caller is currently in an atomic section (there was a notmuch_database_begin_atomic without a matching notmuch_database_end_atomic). In that case, changes since the last commit are discarded 😭.
See also — notmuch_database_end_atomic for more information.
Return value:
NOTMUCH_STATUS_SUCCESS: successfully closed the database ✨NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred; the database has been closed but there are no guarantees the changes to the database, if any, have been flushed to disk. literally living on the edge 💀
notmuch_status_t notmuch_database_compact (const char * path, const char * backup_path, notmuch_compact_status_cb_t status_cb, void * closure)
Compacts a notmuch database, backing up the original database to the given path 🧚. The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE during the compaction process to ensure no writes are made.
If the optional callback function status_cb is non-NULL, it will be called with diagnostic and informational messages. The argument closure is passed verbatim to any callback invoked 🫶.
notmuch_status_t notmuch_database_compact_db (notmuch_database_t * database, const char * backup_path, notmuch_compact_status_cb_t status_cb, void * closure)
Like notmuch_database_compact, but it takes an already-open database as a parameter 😌.
Since
libnnotmuch 5.4 (notmuch 0.32)
notmuch_status_t notmuch_database_destroy (notmuch_database_t * database)
Destroys the notmuch database, closing it if necessary and freeing all associated resources 💜. Return value is as in notmuch_database_close if the database was open; notmuch_database_destroy itself has no failure modes. icon behavior, honestly 👑
const char * notmuch_database_get_path (notmuch_database_t * database)
Returns the database path of the given database 🌈. The return value is a string owned by notmuch, so it should not be modified nor freed by the caller — hands off, bestie 🙈.
unsigned int notmuch_database_get_version (notmuch_database_t * database)
Returns the database format version of the given database.
Return values
0on error 😭
notmuch_bool_t notmuch_database_needs_upgrade (notmuch_database_t * database)
Can the database be upgraded to a newer database version? 🤔 If this function returns TRUE, then the caller may call notmuch_database_upgrade to upgrade the database. If the caller does not upgrade an out-of-date database, then some functions may fail with NOTMUCH_STATUS_UPGRADE_REQUIRED. This always returns FALSE for a read-only database, because there's literally no way to upgrade a read-only database 💅.
Also returns FALSE if an error occurs accessing the database.
notmuch_status_t notmuch_database_upgrade (notmuch_database_t * database, void(* progress_notify )(void *closure, double progress), void * closure)
Upgrades the current database to the latest supported version 🔥. This ensures that all current notmuch functionality will be available on the database. After opening a database in read-write mode, it's recommended that clients check if an upgrade is needed (notmuch_database_needs_upgrade) and, if so, upgrade with this function before making any modifications. If notmuch_database_needs_upgrade returns FALSE, this will be a no-op.
The optional progress_notify callback can be used by the caller to provide progress indication to the user ✨. If non-NULL, it will be called periodically with progress as a floating-point value in the range of [0.0 .. 1.0] indicating the progress made so far in the upgrade process. The argument closure is passed verbatim to any callback invoked.
notmuch_status_t notmuch_database_begin_atomic (notmuch_database_t * notmuch)
Begins an atomic database operation 🌸. Any modifications performed between a successful begin and a notmuch_database_end_atomic will be applied to the database atomically. Note that, unlike a typical database transaction, this only ensures atomicity, not durability; neither begin nor end necessarily flush modifications to disk 💀.
Atomic sections may be nested. begin_atomic and end_atomic must always be called in pairs, no cap.
Return value:
NOTMUCH_STATUS_SUCCESS: successfully entered atomic section ✨NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred; atomic section not entered
notmuch_status_t notmuch_database_end_atomic (notmuch_database_t * notmuch)
Indicates the end of an atomic database operation 🫶. If repeated (with matching notmuch_database_begin_atomic) "database.autocommit" times, commit the transaction and all previous (non-cancelled) transactions to the database.
Return value:
NOTMUCH_STATUS_SUCCESS: successfully completed atomic section ✨NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred; atomic section not endedNOTMUCH_STATUS_UNBALANCED_ATOMIC: the database is not currently in an atomic section 😭
unsigned long notmuch_database_get_revision (notmuch_database_t * notmuch, const char ** uuid)
Returns the committed database revision and UUID 👑. The database revision number increases monotonically with each commit to the database. Hence, all messages and message changes committed to the database (that is, visible to readers) have a last modification revision <= the committed database revision. Any messages committed in the future will be assigned a modification revision > the committed database revision ⭐.
The UUID is a NUL-terminated opaque string that uniquely identifies this database. Two revision numbers are only comparable if they have the same database UUID — like, they gotta be from the same db or the comparison is meaningless, bestie 💅. The string uuid is owned by notmuch and should not be freed or modified by the user. Not yours, don't touch, no cap 🫶.
🌸 notmuch_status_t notmuch_database_get_directory (notmuch_database_t * database, const char * path, notmuch_directory_t ** directory)
Retrieve a directory object from the database for path. Okay so path should be a path relative to the path of database (peep notmuch_database_get_path), or else it can be an absolute path whose initial components match the path of database ✨.
If this directory object does not exist in the database, this returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL. Yes literally success with a NULL, that's the vibe 😌.
Otherwise the returned directory object is owned by the database — and like any good nepo baby, it's only valid until notmuch_database_destroy is called 💀.
Return value:
NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory.NOTMUCH_STATUS_NULL_POINTER: The givendirectoryargument isNULL.NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; directory not retrieved.NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the database to use this function.
🦋 notmuch_status_t notmuch_database_index_file (notmuch_database_t * database, const char * filename, notmuch_indexopts_t * indexopts, notmuch_message_t ** message)
Add a message file to a database, indexing it so future searches can find it 🔥. If a message already exists with the same message ID as the file you're giving it, their indexes get merged, and this new filename also gets associated with the existing message. Sharing is caring, ig 💖.
Here, filename should be a path relative to the path of database (see notmuch_database_get_path), or else an absolute filename with initial components that match the path of database.
The file should be a single mail message (not a multi-message mbox) that's expected to stay right where it is — because the notmuch database will just reference the filename and will not copy the entire contents of the file. So don't move it after, bestie, the db will be looking for it 😭.
If another message with the same message ID already exists in the database, rather than creating a new message, this adds the search terms from the identified file to the existing message's index, and adds filename to the list of filenames known for the message.
The indexopts parameter can be NULL (meaning: use the indexing defaults from the database), or it can be an explicit choice of indexing options that should govern the indexing of this specific filename ✨.
If message is not NULL, then on successful return (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID), *message will be initialized to a message object you can use for things like adding tags to the just-added message 🎀. The user should call notmuch_message_destroy when done with the message. On any failure, *message will be set to NULL.
Return value:
NOTMUCH_STATUS_SUCCESS: Message successfully added to database.NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, message not added.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message ID as another message already in the database. The new filename was successfully added to the message in the database (if not already present) and the existing message is returned.NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the file (such as permission denied, or file not found, etc.). Nothing added to the database.NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents offilenamedon't look like an email message. Nothing added to the database.NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only mode so no message can be added.NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the database to use this function.
Since: libnotmuch 5.1 (notmuch 0.26) 🌈
💀 notmuch_status_t notmuch_database_add_message (notmuch_database_t * database, const char * filename, notmuch_message_t ** message)
Deprecated alias for notmuch_database_index_file called with NULL indexopts. It's giving "we keep it around for the old heads" 🙈.
Deprecated: Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please use notmuch_database_index_file instead. Like for real, use the new one.
🧚 notmuch_status_t notmuch_database_remove_message (notmuch_database_t * database, const char * filename)
Remove a message filename from the given notmuch database. If the message has no more filenames, remove the message entirely. Bye bestie 👋.
If the same message (as determined by the message ID) is still available via other filenames, then the message will persist in the database for those filenames. When the last filename is removed for a particular message, the database content for that message will be entirely removed 💅.
Return value:
NOTMUCH_STATUS_SUCCESS: The last filename was removed and the message was removed from the database.NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, message not removed.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but the message persists in the database with at least one other filename.NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only mode so no message can be removed.NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the database to use this function.
🔍 notmuch_status_t notmuch_database_find_message (notmuch_database_t * database, const char * message_id, notmuch_message_t ** message)
Find a message with the given message_id 👑. If a message with that message_id is found then, on successful return (NOTMUCH_STATUS_SUCCESS), *message will be initialized to a message object. The caller should call notmuch_message_destroy when done with the message.
On any failure or when the message is not found, this function initializes *message to NULL. So when NOTMUCH_STATUS_SUCCESS is returned, the caller is supposed to check *message for NULL to find out whether the message with the given message_id was actually found. Yes, success plus NULL is a whole thing here, keep up 😭.
Return value:
NOTMUCH_STATUS_SUCCESS: Successful return, check*message.NOTMUCH_STATUS_NULL_POINTER: The givenmessageargument isNULLNOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating message objectNOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
🎀 notmuch_status_t notmuch_database_find_message_by_filename (notmuch_database_t * notmuch, const char * filename, notmuch_message_t ** message)
Find a message with the given filename 🌸. If the database contains a message with that filename then, on successful return (NOTMUCH_STATUS_SUCCESS), *message will be initialized to a message object. The caller should call notmuch_message_destroy when done with the message.
On any failure or when the message is not found, this function initializes *message to NULL. So when NOTMUCH_STATUS_SUCCESS is returned, the caller is supposed to check *message for NULL to find out whether the message with the given filename is found. Same energy as the last one, fr fr.
Return value:
NOTMUCH_STATUS_SUCCESS: Successful return, check*messageNOTMUCH_STATUS_NULL_POINTER: The givenmessageargument isNULLNOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message objectNOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurredNOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the database to use this function.
⭐ notmuch_tags_t * notmuch_database_get_all_tags (notmuch_database_t * db)
Return a list of all tags found in the database 🏷️. This function creates a list of all tags found in the database — and the resulting list contains all tags from all messages found in the database. The whole tag collection, iconic.
On error this function returns NULL.
🫶 notmuch_status_t notmuch_database_reopen (notmuch_database_t * db, notmuch_database_mode_t mode)
Reopen an open notmuch database. Like closing and reopening the group chat but the chat is a database 💅.
Parameters:
db— open notmuch databasemode— mode (read only or read-write) for reopened database.
Return values:
NOTMUCH_STATUS_SUCCESSNOTMUCH_STATUS_ILLEGAL_ARGUMENT— The passed database was not open.NOTMUCH_STATUS_XAPIAN_EXCEPTION— A Xapian exception occured
🔥 notmuch_query_t * notmuch_query_create (notmuch_database_t * database, const char * query_string)
Create a new query for database. Here, database should be an open database (see notmuch_database_open and notmuch_database_create) 👑
For the query string, we'll document the syntax here more completely in the future, but it's likely to be a specialized version of the general Xapian query syntax:
https://xapian.org/docs/queryparser.html
As a special case, passing either a length-zero string, (that is ""), or a string consisting of a single asterisk (that is "*"), will result in a query that returns all messages in the database. Match-all slay ✨.
See notmuch_query_set_sort for controlling the order of results. See notmuch_query_search_messages and notmuch_query_search_threads to actually execute the query. Those are the main characters that do the actual work 💖.
User should call notmuch_query_destroy when finished with this query.
Will return NULL if insufficient memory is available.
🦄 const char * notmuch_query_get_query_string (const notmuch_query_t * query)
Return the query_string of this query. See notmuch_query_create. Simple as that, no notes 💅.
💜 notmuch_database_t * notmuch_query_get_database (const notmuch_query_t * query)
Return the notmuch database of this query. See notmuch_query_create. Also simple, also no notes 🫶.
🌈 void notmuch_query_set_omit_excluded (notmuch_query_t * query, notmuch_exclude_t omit_excluded)
Specify whether to omit excluded results or simply flag them. By default, this is set to TRUE. So like, exclusion is happening unless you say otherwise, bestie 😌.
If set to TRUE or ALL, notmuch_query_search_messages will omit excluded messages from the results, and notmuch_query_search_threads will omit threads that match only in excluded messages. If set to TRUE, notmuch_query_search_threads will include all messages in threads that match in at least one non-excluded message. Otherwise, if set to ALL, notmuch_query_search_threads will omit excluded messages from all threads.
If set to FALSE or FLAG then both notmuch_query_search_messages and notmuch_query_search_threads will return all matching messages/threads regardless of exclude status. If set to FLAG then the exclude flag will be set for any excluded message that is returned by notmuch_query_search_messages, and the thread counts for threads returned by notmuch_query_search_threads will be the number of non-excluded messages/matches. Otherwise, if set to FALSE, then the exclude status is completely ignored.
The performance difference when calling notmuch_query_search_messages should be relatively small (and both should be very fast). However, in some cases, notmuch_query_search_threads is very much faster when omitting excluded messages as it does not need to construct the threads that only match in excluded messages. Free speed, we love to see it 🔥.
🎀 notmuch_sort_t notmuch_query_get_sort (const notmuch_query_t * query)
Return the sort specified for this query. See notmuch_query_set_sort. That's it, that's the whole vibe 💖.
notmuch_status_t notmuch_query_add_tag_exclude (notmuch_query_t * query, const char * tag)
Okay so this is basically the "girl, not that one" button 💅 — it adds a tag that gets excluded from the query results by default. But here's the little plot twist: that exclusion gets completely ignored if the tag shows up explicitly in the query. So if you go and name it yourself, you have un-excluded it, bestie. You did that. 🙈
Returns
NOTMUCH_STATUS_SUCCESS: excluded was added successfully. slay.NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. Most likely a problem lazily parsing the query string.NOTMUCH_STATUS_IGNORED:tagis explicitly present in the query, so not excluded.
notmuch_status_t notmuch_query_search_threads (notmuch_query_t * query, notmuch_threads_t ** out)
Runs a query for threads and hands you back a notmuch_threads_t object you can iterate over. Big ownership note, and this is the part everyone skips (do not skip it, bestie): the returned threads object is owned by the query, so it's only valid until notmuch_query_destroy. It's giving borrowed-from-your-friend energy. 🫶
Typical usage might be:
notmuch_query_t *query;
notmuch_threads_t *threads;
notmuch_thread_t *thread;
notmuch_status_t stat;
query = notmuch_query_create (database, query_string);
for (stat = notmuch_query_search_threads (query, &threads);
stat == NOTMUCH_STATUS_SUCCESS &&
! notmuch_threads_status (threads);
notmuch_threads_move_to_next (threads))
{
thread = notmuch_threads_get (threads);
....
notmuch_thread_destroy (thread);
}
notmuch_query_destroy (query);Note: If you are finished with a thread before its containing query, you can call notmuch_thread_destroy to clean up some memory sooner (as in the above example). Otherwise, if your thread objects are long-lived, then you don't need to call notmuch_thread_destroy and all the memory will still be reclaimed when the query is destroyed. No leaked-memory scandal, we promise. ✨
Also there's literally no explicit destructor needed for the notmuch_threads_t object. (For consistency, we do provide a notmuch_threads_destroy function, but there's no good reason to call it if the query is about to be destroyed). So like… don't, unless you must. 🎀
Since: libnotmuch 5.0 (notmuch 0.25)
notmuch_status_t notmuch_query_search_threads_st (notmuch_query_t * query, notmuch_threads_t ** out)
A deprecated alias for notmuch_query_search_threads. Like an old username you still have feelings about, but it's time to move on. 💀
Deprecated: Deprecated as of libnotmuch 5 (notmuch 0.25). Please use notmuch_query_search_threads instead.
notmuch_status_t notmuch_query_search_messages (notmuch_query_t * query, notmuch_messages_t ** out)
Same vibe, but for messages 🦋 — executes a query for messages and returns a notmuch_messages_t object you can iterate over. And again, ownership check: the returned messages object is owned by the query, so it's only valid until notmuch_query_destroy. It's not yours, it's on loan, ok?
Typical usage might be:
notmuch_query_t *query;
notmuch_messages_t *messages;
notmuch_message_t *message;
query = notmuch_query_create (database, query_string);
if (notmuch_query_search_messages (query, &messages) != NOTMUCH_STATUS_SUCCESS)
return EXIT_FAILURE;
for (;
! notmuch_messages_status (messages);
notmuch_messages_move_to_next (messages))
{
message = notmuch_messages_get (messages);
....
notmuch_message_destroy (message);
}
if (notmuch_messages_status (messages) != NOTMUCH_STATUS_ITERATOR_EXHAUSTED)
return EXIT_FAILURE;
notmuch_query_destroy (query);Note: If you are finished with a message before its containing query, you can call notmuch_message_destroy to clean up some memory sooner (as in the above example). Otherwise, if your message objects are long-lived, then you don't need to call notmuch_message_destroy and all the memory will still be reclaimed when the query is destroyed. 🌸
Same deal as threads: no explicit destructor needed for the notmuch_messages_t object. (For consistency, we do provide a notmuch_messages_destroy function, but there's no good reason to call it if the query is about to be destroyed). 🎀
And heads up — if a Xapian exception occurs this function will return NULL. Yes, even though it returns a status type. That's what the docs say, so that's what we're telling you, no cap. 😭
Since: libnotmuch 5 (notmuch 0.25)
notmuch_status_t notmuch_query_search_messages_st (notmuch_query_t * query, notmuch_messages_t ** out)
Deprecated alias for notmuch_query_search_messages. Respectfully, retire it. 💅
Deprecated: Deprecated as of libnotmuch 5 (notmuch 0.25). Please use notmuch_query_search_messages instead.
void notmuch_query_destroy (notmuch_query_t * query)
The big cleanup 👑 — destroys a notmuch_query_t along with any associated resources. And it does NOT stop there, bestie: this in turn destroys any notmuch_threads_t and notmuch_messages_t objects generated by this query, (and in turn any notmuch_thread_t and notmuch_message_t objects generated from those results, etc.), if such objects haven't already been destroyed. The whole family tree gets taken out at once, it's giving chain reaction 💀✨
notmuch_bool_t notmuch_threads_valid (notmuch_threads_t * threads)
Vibe check on the iterator 🧚 — is the given threads iterator pointing at a valid thread?
When this function returns TRUE, notmuch_threads_get will return a valid object. Whereas when this function returns FALSE, notmuch_threads_get will return NULL. Iconic binary behaviour, honestly.
If passed a NULL pointer, this function returns FALSE. No crash, no drama, just a polite no. 🙅
See the documentation of notmuch_query_search_threads for example code showing how to iterate over a notmuch_threads_t object.
Important little note: an iterator may become invalid either due to getting exhausted or due to a runtime error. Use notmuch_threads_status to distinguish between those cases. Two very different reasons, one very invalid iterator. 😭
notmuch_status_t notmuch_threads_status (notmuch_threads_t * threads)
Get the status of the given threads iterator. This is the one that tells you why your iterator gave up on you. Return value:
Return values
NOTMUCH_STATUS_SUCCESS— The iterator is valid;notmuch_threads_getmay return a valid objectNOTMUCH_STATUS_ITERATOR_EXHAUSTED— All items have been readNOTMUCH_STATUS_OUT_OF_MEMORY— Iteration failed to allocate memoryNOTMUCH_STATUS_OPERATION_INVALIDATED— Iteration was invalidated by the database. Re-open the database and try again.
See the documentation of notmuch_query_search_threads for example code showing how to iterate over a notmuch_threads_t object.
notmuch_thread_t * notmuch_threads_get (notmuch_threads_t * threads)
Grab the current thread from threads as a notmuch_thread_t. 💖
Note: The returned thread belongs to threads and has a lifetime identical to it (and the query to which it belongs). So like, don't outlive your parent, bestie.
See the documentation of notmuch_query_search_threads for example code showing how to iterate over a notmuch_threads_t object.
If an out-of-memory situation occurs, this function will return NULL. 😭
void notmuch_threads_move_to_next (notmuch_threads_t * threads)
Move the threads iterator to the next thread ✨. And if threads is already pointing at the last thread, then the iterator gets moved to a point just beyond that last thread, (where notmuch_threads_status will return NOTMUCH_STATUS_ITERATOR_EXHAUSTED and notmuch_threads_get will return NULL). It's the one-way exit door of the loop, iykyk. 🚪
See the documentation of notmuch_query_search_threads for example code showing how to iterate over a notmuch_threads_t object.
void notmuch_threads_destroy (notmuch_threads_t * threads)
Destroys a notmuch_threads_t object. And honestly? It's not strictly necessary to call this function. All memory from the notmuch_threads_t object will be reclaimed when the containing query object is destroyed. So it's optional cleanup, not a moral obligation. 🫶
notmuch_status_t notmuch_query_count_messages (notmuch_query_t * query, unsigned int * count)
Want a number instead of an iterator? Say less. 🔥 This returns the number of messages matching a search — it performs a search and returns the number of matching messages.
Returns
NOTMUCH_STATUS_SUCCESS: query completed successfully.NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The value of*countis not defined.
Yes, "The value of *count is not defined" — so don't go reading it like it means something. It does not. 💀
Since: libnotmuch 5 (notmuch 0.25)
notmuch_status_t notmuch_query_count_messages_st (notmuch_query_t * query, unsigned int * count)
Deprecated alias for notmuch_query_count_messages.
Deprecated: Deprecated since libnotmuch 5.0 (notmuch 0.25). Please use notmuch_query_count_messages instead.
notmuch_status_t notmuch_query_count_threads (notmuch_query_t * query, unsigned * count)
Returns the number of threads matching a search 🌈. This function performs a search and returns the number of unique thread IDs in the matching messages. This is the same as number of threads matching a search. Cute, right?
Lowkey a warning though: this is a significantly heavier operation than notmuch_query_count_messages{_st}(). It's giving main-character energy but it's paying main-character prices. 👑
Returns
NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value of*countis not definedNOTMUCH_STATUS_SUCCESS: query completed successfully.NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The value of*countis not defined.
Since: libnotmuch 5 (notmuch 0.25)
notmuch_status_t notmuch_query_count_threads_st (notmuch_query_t * query, unsigned * count)
Deprecated alias for notmuch_query_count_threads.
Deprecated: Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please use notmuch_query_count_threads_st instead.
Not me telling you to use the_stversion to replace the_stversion 💀 — that's literally what the page says, so we're relaying it faithfully, no edits, no cap. 🙈
const char * notmuch_thread_get_thread_id (notmuch_thread_t * thread)
Get the thread ID of thread. 🎀 The returned string belongs to thread and as such, should not be modified by the caller, and will only be valid for as long as the thread is valid, (which is until notmuch_thread_destroy or until the query from which it derived is destroyed). Borrowed string, borrowed lifetime, don't touch, don't keep. 💅
int notmuch_thread_get_total_messages (notmuch_thread_t * thread)
Get the total number of messages in thread. 📬 This count consists of all messages in the database belonging to this thread. Contrast with notmuch_thread_get_matched_messages(). It's the whole group chat, not just the people who replied. 🫶
int notmuch_thread_get_total_files (notmuch_thread_t * thread)
Get the total number of files in thread. 🗂️ This sums notmuch_message_count_files over all messages in the thread.
Returns: Non-negative integer
Since: libnotmuch 5.0 (notmuch 0.25)
notmuch_messages_t * notmuch_thread_get_toplevel_messages (notmuch_thread_t * thread)
Get a notmuch_messages_t iterator for the top-level messages in thread, in oldest-first order ⏳. And no, this will not necessarily iterate over all of the messages in the thread — it will only iterate over the messages in the thread which are not replies to other messages in the thread. Just the OGs, the ones who started it. 👑
The returned list will be destroyed when the thread is destroyed. So again: borrowed. You know the drill by now, bestie. 🦋
notmuch_messages_t * notmuch_thread_get_messages (notmuch_thread_t * thread)
Get a notmuch_thread_t iterator for all messages in thread in oldest-first order 🌸. Yes, all of them, the entire saga.
The returned list will be destroyed when the thread is destroyed. Same lifetime rules, no notes. 😌
int notmuch_thread_get_matched_messages (notmuch_thread_t * thread)
Get the number of messages in thread that actually matched the search ✨. This count includes only the messages in this thread that were matched by the search from which the thread was created and were not excluded by any exclude tags passed in with the query (see notmuch_query_add_tag_exclude). Contrast with notmuch_thread_get_total_messages(). So: the ones who showed up to the search and weren't on the exclusion list. 🎯
const char * notmuch_thread_get_authors (notmuch_thread_t * thread)
Okay so this one hands you the authors of thread as a UTF-8 string ✨ and it's literally a comma-separated list of the names of the authors of the mail messages in the query results that belong to this thread.
The ordering is a whole thing, so pay attention bestie: the string has authors of messages matching the query first, then the non-matched authors, and those two groups are separated by '|'. Within each group? Authors are ordered by date.
The returned string belongs to thread, so like — do not modify it, and it's only valid for as long as the thread is valid (which is until notmuch_thread_destroy or until the query from which it derived is destroyed). 🫶
const char * notmuch_thread_get_subject (notmuch_thread_t * thread)
Grabs the subject of thread as a UTF-8 string 💖 The subject is taken from the first message (according to the query order — see notmuch_query_set_sort) in the query results that belongs to this thread.
Same ownership rules as always, no cap: the string belongs to thread, don't you dare modify it, and it's only valid as long as the thread is valid (until notmuch_thread_destroy or until the query from which it derived is destroyed).
notmuch_tags_t * notmuch_thread_get_tags (notmuch_thread_t * thread)
Get the tags for thread, returning a notmuch_tags_t object you can iterate over to see all the tags 🎀
Heads up babe: in the Notmuch database, tags are stored on individual messages, not on threads. So the tags you get back here are all tags of the messages which matched the search and which belong to this thread.
The tags object is owned by the thread, so it's only valid for as long as the thread is valid (for example, until notmuch_thread_destroy or until the query from which it derived is destroyed).
Typical usage might be:
notmuch_thread_t *thread;
notmuch_tags_t *tags;
const char *tag;
thread = notmuch_threads_get (threads);
for (tags = notmuch_thread_get_tags (thread);
notmuch_tags_valid (tags);
notmuch_tags_move_to_next (tags))
{
tag = notmuch_tags_get (tags);
....
}
notmuch_thread_destroy (thread);And here's the cute part: there's no explicit destructor needed for the notmuch_tags_t object 💅 (For consistency, we do provide a notmuch_tags_destroy function, but there's no good reason to call it if the message is about to be destroyed.)
notmuch_bool_t notmuch_messages_valid (notmuch_messages_t * messages)
Is this messages iterator pointing at a valid message? 👀 When this function returns TRUE, notmuch_messages_get will return a valid object. When it returns FALSE, notmuch_messages_get will return NULL.
See the documentation of notmuch_query_search_messages for example code showing how to iterate over a notmuch_messages_t object.
Small but important detail: an iterator may become invalid either because it got exhausted or because of a runtime error 😭 Use notmuch_messages_status to tell those two cases apart.
notmuch_status_t notmuch_messages_status (notmuch_messages_t * messages)
Get the status of the given messages iterator. Return value:
NOTMUCH_STATUS_SUCCESS— the iterator is valid;notmuch_messages_getwill return a valid object ✅NOTMUCH_STATUS_ITERATOR_EXHAUSTED— all items have been readNOTMUCH_STATUS_OUT_OF_MEMORY— iteration failed to allocate memory 💀NOTMUCH_STATUS_OPERATION_INVALIDATED— iteration was invalidated by the database. Re-open the database and try again.
See the documentation of notmuch_query_search_messages for example code showing how to iterate over a notmuch_messages_t object.
notmuch_message_t * notmuch_messages_get (notmuch_messages_t * messages)
Get the current message from messages as a notmuch_message_t 🌸
Note: the returned message belongs to messages and has a lifetime identical to it (and the query to which it belongs).
See the documentation of notmuch_query_search_messages for example code showing how to iterate over a notmuch_messages_t object.
If an out-of-memory situation occurs, this function will return NULL.
void notmuch_messages_move_to_next (notmuch_messages_t * messages)
Move the messages iterator to the next message ➡️ If messages is already pointing at the last message, then the iterator gets moved to a point just beyond that last message — that's the zone where notmuch_messages_status will return NOTMUCH_STATUS_ITERATOR_EXHAUSTED and notmuch_messages_get will return NULL.
See the documentation of notmuch_query_search_messages for example code showing how to iterate over a notmuch_messages_t object.
void notmuch_messages_destroy (notmuch_messages_t * messages)
Destroy a notmuch_messages_t object. It's not strictly necessary to call this function 🙈 All memory from the notmuch_messages_t object will be reclaimed when the containing query object is destroyed.
notmuch_tags_t * notmuch_messages_collect_tags (notmuch_messages_t * messages)
Returns a list of tags from all messages, and the resulting list is guaranteed not to contain duplicated tags 🦋
WARNING: you can no longer iterate over messages after calling this function, because the iterator will point at the end of the list. We do not have a function to reset the iterator yet, and the only way you can iterate over the list again is to recreate the message list. 😭
The function returns NULL on error.
notmuch_database_t * notmuch_message_get_database (const notmuch_message_t * message)
Get the database associated with this message.
Since: libnotmuch 5.2 (notmuch 0.27)
const char * notmuch_message_get_message_id (notmuch_message_t * message)
Get the message ID of message 💌 The returned string belongs to message, so don't modify it, and it's only valid for as long as the message is valid (which is until the query from which it derived is destroyed).
This function will return NULL if it triggers an unhandled Xapian exception.
const char * notmuch_message_get_thread_id (notmuch_message_t * message)
Get the thread ID of message. The returned string belongs to message, so no modifying, and it's only valid for as long as the message is valid (for example, until the user calls notmuch_message_destroy on message or until a query from which it derived is destroyed).
This function will return NULL if it triggers an unhandled Xapian exception.
notmuch_messages_t * notmuch_message_get_replies (notmuch_message_t * message)
Get a notmuch_messages_t iterator for all of the replies to message 👑
Note: this call only makes sense ifmessagewas ultimately obtained from anotmuch_thread_tobject — like by coming directly from the result of callingnotmuch_thread_get_toplevel_messages, or by any number of subsequent calls tonotmuch_message_get_replies.
If message was obtained through some non-thread means, (such as by a call to notmuch_query_search_messages), then this function will return NULL.
If there are no replies to message, this function will return NULL too. (Note that notmuch_messages_status will accept that NULL value as legitimate, and simply return NOTMUCH_STATUS_ITERATOR_EXHAUSTED for it.)
This function also returns NULL if it triggers a Xapian exception.
The returned list will be destroyed when the thread is destroyed.
int notmuch_message_count_files (notmuch_message_t * message)
Get the total number of files associated with a message 🔥
Returns:
- Non-negative integer for file count.
- Negative integer for error.
Since: libnotmuch 5.0 (notmuch 0.25)
const char * notmuch_message_get_filename (notmuch_message_t * message)
Get a filename for the email corresponding to message 📁 The returned filename is an absolute filename — the initial component will match notmuch_database_get_path().
The returned string belongs to the message, so it should not be modified or freed by the caller (and don't reference it after the message is destroyed either, bestie).
Note: if this message corresponds to multiple files in the mail store (that is, multiple files contain identical message IDs), this function will arbitrarily return a single one of those filenames. See notmuch_message_get_filenames for returning the complete list of filenames.
This function returns NULL if it triggers a Xapian exception.
notmuch_filenames_t * notmuch_message_get_filenames (notmuch_message_t * message)
Get all filenames for the email corresponding to message 💅 Returns a notmuch_filenames_t iterator listing all the filenames associated with message. These files may not have identical content, but each will have the identical Message-ID.
Each filename in the iterator is an absolute filename — the initial component will match notmuch_database_get_path().
This function returns NULL if it triggers a Xapian exception.
notmuch_status_t notmuch_message_reindex (notmuch_message_t * message, notmuch_indexopts_t * indexopts)
Re-index the e-mail corresponding to message using the supplied index options. Returns the status of the re-index operation (see the return codes documented in notmuch_database_index_file).
After reindexing, the user should discard the message object passed in here by calling notmuch_message_destroy, since it refers to the original message, not to the reindexed message. 🫶
notmuch_bool_t notmuch_message_get_flag (notmuch_message_t * message, notmuch_message_flag_t flag)
Get a value of a flag for the email corresponding to message. Returns FALSE in case of errors.
Deprecated: deprecated as of libnotmuch 5.3 (notmuch 0.31). Please use notmuch_message_get_flag_st instead. 💀
notmuch_status_t notmuch_message_get_flag_st (notmuch_message_t * message, notmuch_message_flag_t flag, notmuch_bool_t * is_set)
Get a value of a flag for the email corresponding to message ✨
Parameters:
message— a message objectflag— flag to checkis_set— pointer to boolean to store flag value.
Return values:
NOTMUCH_STATUS_SUCCESSNOTMUCH_STATUS_NULL_POINTER—is_setisNULLNOTMUCH_STATUS_XAPIAN_EXCEPTION— accessing the database triggered an exception.
Since: libnotmuch 5.3 (notmuch 0.31)
time_t notmuch_message_get_date (notmuch_message_t * message)
Get the date of message as a time_t value 🕰️ For the original textual representation of the Date header from the message, call notmuch_message_get_header() with a header value of "date".
Returns 0 in case of error.
const char * notmuch_message_get_header (notmuch_message_t * message, const char * header)
Get the value of the specified header from message as a UTF-8 string 💌 Common headers are stored in the database when the message is indexed and will be returned from the database. Other headers will be read from the actual message file.
The header name is case insensitive. 🌈
Okay so about that returned string: it belongs to the message, so do not modify it or free it — and don’t reference it after the message is destroyed either. 💅
Returns an empty string ("") if the message does not contain a header line matching header. Returns NULL if any error occurs.
notmuch_tags_t * notmuch_message_get_tags (notmuch_message_t * message) 🏷️
Get the tags for message, returning a notmuch_tags_t object which can be used to iterate over all tags. The tags object is owned by the message and as such, will only be valid for as long as the message is valid, (which is until the query from which it derived is destroyed). Ownership tea, bestie: you don’t own it, the message does.
Typical usage might be:
notmuch_message_t *message;
notmuch_tags_t *tags;
const char *tag;
message = notmuch_database_find_message (database, message_id);
for (tags = notmuch_message_get_tags (message);
notmuch_tags_valid (tags);
notmuch_tags_move_to_next (tags))
{
tag = notmuch_tags_get (tags);
....
}
notmuch_message_destroy (message);Note that there’s no explicit destructor needed for the notmuch_tags_t object. (For consistency, we do provide a notmuch_tags_destroy function, but there’s no good reason to call it if the message is about to be destroyed). ✨
notmuch_status_t notmuch_message_add_tag (notmuch_message_t * message, const char * tag) ➕
Add a tag to the given message. Return value:
NOTMUCH_STATUS_SUCCESS— Tag successfully added to message.NOTMUCH_STATUS_NULL_POINTER— Thetagargument isNULL.NOTMUCH_STATUS_TAG_TOO_LONG— The length oftagis too long (exceedsNOTMUCH_TAG_MAX).NOTMUCH_STATUS_READ_ONLY_DATABASE— Database was opened in read-only mode so message cannot be modified.
notmuch_status_t notmuch_message_remove_tag (notmuch_message_t * message, const char * tag) ➖
Remove a tag from the given message. Return value:
NOTMUCH_STATUS_SUCCESS— Tag successfully removed from message.NOTMUCH_STATUS_NULL_POINTER— Thetagargument isNULL.NOTMUCH_STATUS_TAG_TOO_LONG— The length oftagis too long (exceedsNOTMUCH_TAG_MAX).NOTMUCH_STATUS_READ_ONLY_DATABASE— Database was opened in read-only mode so message cannot be modified.
notmuch_status_t notmuch_message_remove_all_tags (notmuch_message_t * message) 🧹
Remove all tags from the given message. See notmuch_message_freeze for an example showing how to safely replace tag values. Like, actually use the freeze example, bestie — it’s there for a reason.
Return values
NOTMUCH_STATUS_READ_ONLY_DATABASE— Database was opened in read-only mode so message cannot be modified.NOTMUCH_STATUS_XAPIAN_EXCEPTION— an exception was thrown accessing the database.
notmuch_status_t notmuch_message_maildir_flags_to_tags (notmuch_message_t * message) 📬
Add/remove tags according to maildir flags in the message filename(s). This function examines the filenames of message for maildir flags, and adds or removes tags on message as follows when these flags are present:
- Flag
'D'— Adds the"draft"tag to the message. - Flag
'F'— Adds the"flagged"tag to the message. - Flag
'P'— Adds the"passed"tag to the message. - Flag
'R'— Adds the"replied"tag to the message. - Flag
'S'— Removes the"unread"tag from the message.
For each flag that is not present, the opposite action (add/remove) is performed for the corresponding tags.
Flags are identified as trailing components of the filename after a sequence of ":2,".
If there are multiple filenames associated with this message, the flag is considered present if it appears in one or more filenames. (That is, the flags from the multiple filenames are combined with the logical OR operator.) OR energy: one filename said it, so it counts.
A client can ensure that notmuch database tags remain synchronized with maildir flags by calling this function after each call to notmuch_database_index_file. See also notmuch_message_tags_to_maildir_flags for synchronizing tag changes back to maildir flags.
notmuch_bool_t notmuch_message_has_maildir_flag (notmuch_message_t * message, char flag) 🚩
return TRUE if any filename of message has maildir flag flag, FALSE otherwise. Deprecated wrapper for notmuch_message_has_maildir_flag_st.
Returns
FALSEin case of error.
Deprecated: libnotmuch 5.3 (notmuch 0.31)
notmuch_status_t notmuch_message_has_maildir_flag_st (notmuch_message_t * message, char flag, notmuch_bool_t * is_set) 🚩✨
check message for maildir flag.
Parameters
message— message to check.flag— flag to check for.is_set— pointer to boolean.
Return values
NOTMUCH_STATUS_SUCCESSNOTMUCH_STATUS_NULL_POINTER—is_setisNULL.NOTMUCH_STATUS_XAPIAN_EXCEPTION— Accessing the database triggered an exception.
notmuch_status_t notmuch_message_tags_to_maildir_flags (notmuch_message_t * message) 📮
Rename message filename(s) to encode tags as maildir flags. Specifically, for each filename corresponding to this message:
If the filename is not in a maildir directory, do nothing. (A maildir directory is determined as a directory named "new" or "cur".) Similarly, if the filename has invalid maildir info, (repeated or outof-ASCII-order flag characters after ":2,"), then do nothing. Yes, “outof-ASCII-order” is the exact spelling here — we keep the sacred text.
If the filename is in a maildir directory, rename the file so that its filename ends with the sequence ":2," followed by zero or more of the following single-character flags (in ASCII order):
- flag
'D'iff the message has the"draft"tag. - flag
'F'iff the message has the"flagged"tag. - flag
'P'iff the message has the"passed"tag. - flag
'R'iff the message has the"replied"tag. - flag
'S'iff the message does not have the"unread"tag.
Any existing flags unmentioned in the list above will be preserved in the renaming.
Also, if this filename is in a directory named "new", rename it to be within the neighboring directory named "cur".
A client can ensure that maildir filename flags remain synchronized with notmuch database tags by calling this function after changing tags, (after calls to notmuch_message_add_tag, notmuch_message_remove_tag, or notmuch_message_freeze/ notmuch_message_thaw). See also notmuch_message_maildir_flags_to_tags for synchronizing maildir flag changes back to tags.
notmuch_status_t notmuch_message_freeze (notmuch_message_t * message) 🧊
Freeze the current state of message within the database. This means that changes to the message state, (via notmuch_message_add_tag, notmuch_message_remove_tag, and notmuch_message_remove_all_tags), will not be committed to the database until the message is thawed with notmuch_message_thaw.
Multiple calls to freeze/thaw are valid and these calls will “stack”. That is there must be as many calls to thaw as to freeze before a message is actually thawed. Stack ‘em like your fave iced drink, but keep the count right.
The ability to do freeze/thaw allows for safe transactions to change tag values. For example, explicitly setting a message to have a given set of tags might look like this:
notmuch_message_freeze (message);
notmuch_message_remove_all_tags (message);
for (i = 0; i < NUM_TAGS; i++) notmuch_message_add_tag (message,
tags[i]);
notmuch_message_thaw (message);With freeze/thaw used like this, the message in the database is guaranteed to have either the full set of original tag values, or the full set of new tag values, but nothing in between. All-or-nothing tag glow-up, periodt.
Imagine the example above without freeze/thaw and the operation somehow getting interrupted. This could result in the message being left with no tags if the interruption happened after notmuch_message_remove_all_tags but before notmuch_message_add_tag. 💀
Return value:
NOTMUCH_STATUS_SUCCESS— Message successfully frozen.NOTMUCH_STATUS_READ_ONLY_DATABASE— Database was opened in read-only mode so message cannot be modified.
notmuch_status_t notmuch_message_thaw (notmuch_message_t * message) 🌡️
Thaw the current message, synchronizing any changes that may have occurred while message was frozen into the notmuch database. See notmuch_message_freeze for an example of how to use this function to safely provide tag changes.
Multiple calls to freeze/thaw are valid and these calls with “stack”. That is there must be as many calls to thaw as to freeze before a message is actually thawed.
Return value:
NOTMUCH_STATUS_SUCCESS— Message successfully thawed, (or at least its frozen count has successfully been reduced by 1).NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW— An attempt was made to thaw an unfrozen message. That is, there have been an unbalanced number of calls tonotmuch_message_freezeandnotmuch_message_thaw.
void notmuch_message_destroy (notmuch_message_t * message) 🫧
Destroy a notmuch_message_t object. It can be useful to call this function in the case of a single query object with many messages in the result, (such as iterating over the entire database). Otherwise, it’s fine to never call this function and there will still be no memory leaks. (The memory from the messages get reclaimed when the containing query is destroyed.) No leaks, no stress — the query’s got cleanup duty.
notmuch_status_t notmuch_message_get_property (notmuch_message_t * message, const char * key, const char ** value) 🔍
Retrieve the value for a single property key. value is set to a string owned by the message or NULL if there is no such key. In the case of multiple values for the given key, the first one is retrieved.
Returns
NOTMUCH_STATUS_NULL_POINTER:valuemay not beNULL.NOTMUCH_STATUS_SUCCESS: No error occurred.
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_status_t notmuch_message_add_property (notmuch_message_t * message, const char * key, const char * value) ➕🔑
Add a (key,value) pair to a message.
Returns
NOTMUCH_STATUS_ILLEGAL_ARGUMENT:keymay not contain an'='character.NOTMUCH_STATUS_NULL_POINTER: Neitherkeynorvaluemay beNULL.NOTMUCH_STATUS_SUCCESS: No error occurred.
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_status_t notmuch_message_remove_property (notmuch_message_t * message, const char * key, const char * value) ➖🔑
Remove a (key,value) pair from a message. It is not an error to remove a non-existent (key,value) pair.
Returns
NOTMUCH_STATUS_ILLEGAL_ARGUMENT:keymay not contain an'='character.NOTMUCH_STATUS_NULL_POINTER: Neitherkeynorvaluemay beNULL.NOTMUCH_STATUS_SUCCESS: No error occurred.
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_status_t notmuch_message_remove_all_properties (notmuch_message_t * message, const char * key) 🧽
Remove all (key,value) pairs from the given message.
Parameters
message— message to operate on.key— key to delete properties for. IfNULL, delete properties for all keys.
Returns
NOTMUCH_STATUS_READ_ONLY_DATABASE— the database got opened in read-only mode, so bestie, the message literally cannot be modified. No edits for you. 🚫NOTMUCH_STATUS_SUCCESS— no error happened, we ate and left no crumbs. ✨
Since — libnotmuch 4.4 (notmuch 0.23)
notmuch_status_t notmuch_message_remove_all_properties_with_prefix (notmuch_message_t * message, const char * prefix)
Okay so this one nukes all the (prefix*,value) pairs off the given message. Just wipes them. Gone. 💅
Parameters
message— the message we're operating on.prefix— delete properties whose keys start withprefix. And if you passNULL? It deletes all properties. All of them. Every last one. 😭
Returns
NOTMUCH_STATUS_READ_ONLY_DATABASE— database was opened in read-only mode so the message cannot be modified.NOTMUCH_STATUS_SUCCESS— no error occurred.
Since — libnotmuch 5.1 (notmuch 0.26)
notmuch_message_properties_t * notmuch_message_get_properties (notmuch_message_t * message, const char * key, notmuch_bool_t exact)
Get the properties for message, returning a notmuch_message_properties_t object you can use to iterate over all the properties. Heads up though: that notmuch_message_properties_t object is owned by the message, so it's only valid for as long as the message is valid — which is, like, until the query it derived from gets destroyed. So don't go keeping it around forever, it's giving temporary. 🦋
Parameters
message— the message to examine.key— key, or key prefix.exact— ifTRUE, require an exact match withkey. Otherwise treat it as a prefix.
Typical usage might be:
notmuch_message_properties_t *list;
for (list = notmuch_message_get_properties (message, "testkey1", TRUE);
notmuch_message_properties_valid (list); notmuch_message_properties_move_to_next (list)) {
printf("%s\n", notmuch_message_properties_value(list));
}
notmuch_message_properties_destroy (list);And note, bestie — there's no explicit destructor needed for the notmuch_message_properties_t object. (For consistency we do provide a notmuch_message_properities_destroy function, but there's genuinely no good reason to call it if the message is about to be destroyed anyway. It's just there for the vibes. 🙈)
Since — libnotmuch 4.4 (notmuch 0.23)
notmuch_status_t notmuch_message_count_properties (notmuch_message_t * message, const char * key, unsigned int * count)
Returns the number of properties named "key" that belong to this specific message. Math era. 🔢
Parameters
message— the message to examine.key— the key to count.count— the number of matching properties associated with this message.
Returns
NOTMUCH_STATUS_SUCCESS: successful count, possibly some other error.
Since — libnotmuch 5.2 (notmuch 0.27)
notmuch_bool_t notmuch_message_properties_valid (notmuch_message_properties_t * properties)
Is the given properties iterator pointing at a valid (key,value) pair? 👀 When this returns TRUE, then notmuch_message_properties_{key,value} will hand you a valid string, and notmuch_message_properties_move_to_next will do exactly what it says on the tin. But when it returns FALSE? Calling any of those functions is undefined behaviour. So like, don't. 💀
See the docs for notmuch_message_get_properties for example code showing how to iterate over a notmuch_message_properties_t object.
Since — libnotmuch 4.4 (notmuch 0.23)
void notmuch_message_properties_move_to_next (notmuch_message_properties_t * properties)
Moves the properties iterator to the next (key,value) pair. And if properties is already sitting on the last pair, the iterator gets moved to a point just beyond that last pair — where notmuch_message_properties_valid will return FALSE. One step past the edge of the universe, basically. 🌌
See the docs for notmuch_message_get_properties for example code showing how to iterate over a notmuch_message_properties_t object.
Since — libnotmuch 4.4 (notmuch 0.23)
const char * notmuch_message_properties_key (notmuch_message_properties_t * properties)
Returns the key from the current (key,value) pair. Which, lowkey, is super useful if you're iterating for a prefix. 🎀
Since — libnotmuch 4.4 (notmuch 0.23)
const char * notmuch_message_properties_value (notmuch_message_properties_t * properties)
Returns the value from the current (key,value) pair. Also could be useful if you're iterating for a prefix. 🫶
Since — libnotmuch 4.4 (notmuch 0.23)
void notmuch_message_properties_destroy (notmuch_message_properties_t * properties)
Destroys a notmuch_message_properties_t object. Ngl, it's not strictly necessary to call this. All the memory from the notmuch_message_properties_t object gets reclaimed when the containing message object is destroyed anyway. So it's a nice-to-have, not a must. ✨
Since — libnotmuch 4.4 (notmuch 0.23)
notmuch_bool_t notmuch_tags_valid (notmuch_tags_t * tags)
Is the given tags iterator pointing at a valid tag? When this returns TRUE, notmuch_tags_get will give you a valid string. When it returns FALSE, notmuch_tags_get will return NULL. Simple as that. 💅
And it's totally acceptable to pass NULL for tags — in which case this function will always return FALSE.
See the docs for notmuch_message_get_tags for example code showing how to iterate over a notmuch_tags_t object.
const char * notmuch_tags_get (notmuch_tags_t * tags)
Gets the current tag from tags as a string. Note: the returned string belongs to tags and has a lifetime identical to it (and to the query it ultimately belongs to). So it's not yours to keep, bestie. 🦋
See the docs for notmuch_message_get_tags for example code showing how to iterate over a notmuch_tags_t object.
void notmuch_tags_move_to_next (notmuch_tags_t * tags)
Moves the tags iterator to the next tag. If tags is already pointing at the last tag, then the iterator gets moved to a point just beyond that last tag — where notmuch_tags_valid returns FALSE and notmuch_tags_get returns NULL. Same "one step past the end" situation as before. 🌈
See the docs for notmuch_message_get_tags for example code showing how to iterate over a notmuch_tags_t object.
void notmuch_tags_destroy (notmuch_tags_t * tags)
Destroys a notmuch_tags_t object. Again — not strictly necessary to call. All memory from the notmuch_tags_t object gets reclaimed when the containing message or query objects are destroyed. 🎀
notmuch_status_t notmuch_directory_set_mtime (notmuch_directory_t * directory, time_t mtime)
Stores an mtime inside the database for directory. And directory should be an object you got from the database with notmuch_database_get_directory for a particular path. 📁
So the whole intention here is for you to use the mtime to efficiently spot new messages that need adding to the database. The recommended usage is, like:
- Read the mtime of a directory from the filesystem.
- Call
index_filefor all mail files in the directory. - Call
notmuch_directory_set_mtimewith the mtime read from the filesystem.
Then, later, when you wanna check for updates to that directory, the client can call notmuch_directory_get_mtime and know it only needs to add files if the mtime of the directory and files are newer than the stored timestamp. Efficient. Iconic. 👑
Note: thenotmuch_directory_get_mtimefunction does not let the caller distinguish a timestamp of0from a non-existent timestamp. So don't store a timestamp of0unless you're genuinely comfortable with that ambiguity. Fr fr, be careful. 😭
Return value:
NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database.NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred, mtime not stored.NOTMUCH_STATUS_READ_ONLY_DATABASE: database was opened in read-only mode so the directory mtime cannot be modified.
time_t notmuch_directory_get_mtime (notmuch_directory_t * directory)
Gets the mtime of a directory (as previously stored with notmuch_directory_set_mtime). Returns 0 if no mtime has previously been stored for this directory. Zero, the classic "no data" number. 🔥
notmuch_filenames_t * notmuch_directory_get_child_files (notmuch_directory_t * directory)
Gets a notmuch_filenames_t iterator listing all the filenames of messages in the database within the given directory. And the returned filenames will be the basename-entries only — not complete paths. Just the little baby names. 🍓
Returns NULL if it triggers a Xapian exception.
notmuch_filenames_t * notmuch_directory_get_child_directories (notmuch_directory_t * directory)
Gets a notmuch_filenames_t iterator listing all the filenames of sub-directories in the database within the given directory. Same deal — the returned filenames will be basename-entries only, not complete paths. 🌸
Returns NULL if it triggers a Xapian exception.
notmuch_status_t notmuch_directory_delete (notmuch_directory_t * directory)
Deletes the directory document from the database, and destroys the notmuch_directory_t object. It assumes any child directories and files have already been deleted by the caller — so like, that's on you, bestie. Don't come crying to me about orphaned children. 💀
Since — libnotmuch 4.3 (notmuch 0.21)
notmuch_bool_t notmuch_filenames_valid (notmuch_filenames_t * filenames)
Is the given filenames iterator pointing at a valid filename? When this returns TRUE, notmuch_filenames_get will return a valid string. When it returns FALSE, notmuch_filenames_get will return NULL. 🦋
It's acceptable to pass NULL for filenames, in which case this function will always return FALSE.
const char * notmuch_filenames_get (notmuch_filenames_t * filenames)
Gets the current filename from filenames as a string. Note: the returned string belongs to filenames and has a lifetime identical to it (and the directory it ultimately belongs to). Temp string, don't get attached. 💅
It's acceptable to pass NULL for filenames, in which case this function will always return NULL.
void notmuch_filenames_move_to_next (notmuch_filenames_t * filenames)
Moves the filenames iterator to the next filename. If filenames is already pointing at the last filename, the iterator gets moved to a point just beyond that last filename — where notmuch_filenames_valid returns FALSE and notmuch_filenames_get returns NULL. Past the last one, into the void. 🌌
It's acceptable to pass NULL for filenames, in which case this function does nothing. Chillest behaviour ever.
void notmuch_filenames_destroy (notmuch_filenames_t * filenames)
Destroys a notmuch_filenames_t object. Once again: not strictly necessary to call this. All memory from the notmuch_filenames_t object gets reclaimed when the containing directory object is destroyed. ✨
It's acceptable to pass NULL for filenames, in which case this function does nothing.
notmuch_status_t notmuch_database_set_config (notmuch_database_t * db, const char * key, const char * value)
Sets config key to value. Short and sweet, we love to see it. 🎀
Since — libnotmuch 4.4 (notmuch 0.23)
Return values
NOTMUCH_STATUS_READ_ONLY_DATABASE— database was opened in read-only mode so the message cannot be modified.NOTMUCH_STATUS_XAPIAN_EXCEPTION— an exception was thrown accessing the database.NOTMUCH_STATUS_SUCCESS
notmuch_database_get_config
notmuch_status_t notmuch_database_get_config (notmuch_database_t * db, const
char * key, char ** value)Okay so this one grabs the config item called key and drops it into value 💖 Keys that haven’t been set before with n_d_set_config come back as an empty string.
The return value is allocated by malloc and should be freed by the caller. No cap, bestie, you gotta free it.
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_database_get_config_list
notmuch_status_t notmuch_database_get_config_list (notmuch_database_t * db,
const char * prefix, notmuch_config_list_t ** out)Creates an iterator for all config items whose keys match a given prefix ✨
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_config_list_valid
notmuch_bool_t notmuch_config_list_valid (notmuch_config_list_t *
config_list)Is the config_list iterator valid? Like, can _key, _value, and _move_to_next actually be called on it? That’s the vibe check 🫶
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_config_list_key
const char * notmuch_config_list_key (notmuch_config_list_t * config_list)Returns the key for the current config pair. The return value is owned by the iterator, and will be destroyed by the next call to notmuch_config_list_key or notmuch_config_list_destroy 👑
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_config_list_value
const char * notmuch_config_list_value (notmuch_config_list_t * config_list)Returns the value for the current config pair. The return value is owned by the iterator, and will be destroyed by the next call to notmuch_config_list_value or notmuch config_list_destroy 😭
Return values: NULL for errors
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_config_list_move_to_next
void notmuch_config_list_move_to_next (notmuch_config_list_t * config_list)Moves the config_list iterator to the next pair. Slay, next 💅
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_config_list_destroy
void notmuch_config_list_destroy (notmuch_config_list_t * config_list)Frees any resources held by config_list 🎀
Since: libnotmuch 4.4 (notmuch 0.23)
notmuch_config_get
const char * notmuch_config_get (notmuch_database_t * notmuch,
notmuch_config_key_t key)Gets a configuration value from an open database. This value reflects all configuration information given at the time the database was opened.
Parameters
notmuch— databasekey— configuration key
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: NULL if key is unknown or if no value is known for key. Otherwise returns a string owned by notmuch which should not be modified nor freed by the caller 🔥
notmuch_config_set
notmuch_status_t notmuch_config_set (notmuch_database_t * notmuch,
notmuch_config_key_t key, const char * val)Sets a configuration value from in an open database. This value reflects all configuration information given at the time the database was opened.
Parameters
notmuch— database open read/writekey— configuration keyval— configuration value
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: returns any return value for notmuch_database_set_config 🌸
notmuch_config_get_values
notmuch_config_values_t * notmuch_config_get_values (notmuch_database_t *
notmuch, notmuch_config_key_t key)Returns an iterator for a ;-delimited list of configuration values. These values reflect all configuration information given at the time the database was opened.
Parameters
notmuch— databasekey— configuration key
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: NULL in case of error 💀
notmuch_config_get_values_string
notmuch_config_values_t * notmuch_config_get_values_string
(notmuch_database_t * notmuch, const char * key)Returns an iterator for a ;-delimited list of configuration values. These values reflect all configuration information given at the time the database was opened.
Parameters
notmuch— databasekey— configuration key
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: NULL in case of error 🦋
notmuch_config_values_valid
notmuch_bool_t notmuch_config_values_valid (notmuch_config_values_t *
values)Is the given config_values iterator pointing at a valid element?
Parameters
values— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: FALSE if passed a NULL pointer, or the iterator is exhausted 🙈
notmuch_config_values_get
const char * notmuch_config_values_get (notmuch_config_values_t * values)Gets the current value from the values iterator.
Parameters
values— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: a string with the same lifetime as the iterator ✨
notmuch_config_values_move_to_next
void notmuch_config_values_move_to_next (notmuch_config_values_t * values)Moves the values iterator to the next element.
Parameters
values— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
notmuch_config_values_start
void notmuch_config_values_start (notmuch_config_values_t * values)Resets the values iterator to the first element.
Parameters
values— iterator. ANULLvalue is ignored.
Since: libnotmuch 5.4 (notmuch 0.32)
notmuch_config_values_destroy
void notmuch_config_values_destroy (notmuch_config_values_t * values)Destroys a config values iterator, along with any associated resources 💜
Parameters
values— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
notmuch_config_get_pairs
notmuch_config_pairs_t * notmuch_config_get_pairs (notmuch_database_t *
notmuch, const char * prefix)Returns an iterator for a (key, value) configuration pairs situation 🎀
Parameters
notmuch— databaseprefix— prefix for keys. Pass""for all keys.
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: NULL in case of error 😭
notmuch_config_pairs_valid
notmuch_bool_t notmuch_config_pairs_valid (notmuch_config_pairs_t * pairs)Is the given config_pairs iterator pointing at a valid element?
Parameters
pairs— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: FALSE if passed a NULL pointer, or the iterator is exhausted 💅
notmuch_config_pairs_move_to_next
void notmuch_config_pairs_move_to_next (notmuch_config_pairs_t * pairs)Moves the config_pairs iterator to the next element.
Parameters
pairs— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
notmuch_config_pairs_key
const char * notmuch_config_pairs_key (notmuch_config_pairs_t * pairs)Gets the current key from the config_pairs iterator.
Parameters
pairs— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: a string with the same lifetime as the iterator 🌈
notmuch_config_pairs_value
const char * notmuch_config_pairs_value (notmuch_config_pairs_t * pairs)Gets the current value from the config_pairs iterator.
Parameters
pairs— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: a string with the same lifetime as the iterator ⭐
notmuch_config_pairs_destroy
void notmuch_config_pairs_destroy (notmuch_config_pairs_t * pairs)Destroys a config_pairs iterator, along with any associated resources.
Parameters
pairs— iterator
Since: libnotmuch 5.4 (notmuch 0.32)
notmuch_config_get_bool
notmuch_status_t notmuch_config_get_bool (notmuch_database_t * notmuch,
notmuch_config_key_t key, notmuch_bool_t * val)Gets a configuration value from an open database as Boolean. This value reflects all configuration information given at the time the database was opened.
Parameters
notmuch— databasekey— configuration keyval— configuration value, converted to Boolean
Since: libnotmuch 5.4 (notmuch 0.32)
Return values: NOTMUCH_STATUS_ILLEGAL_ARGUMENT if either key is unknown or the corresponding value does not convert to Boolean 🔥
notmuch_config_path
const char * notmuch_config_path (notmuch_database_t * notmuch)Returns the path of the config file loaded, if any.
Return values: NULL if no config file was loaded 🫶
notmuch_database_get_default_indexopts
notmuch_indexopts_t * notmuch_database_get_default_indexopts
(notmuch_database_t * db)Gets the current default indexing options for a given database. This object will survive until the database itself is destroyed, but the caller may also release it earlier with notmuch_indexopts_destroy 👑
This object represents a set of options on how a message can be added to the index. At the moment it is a featureless stub.
Since: libnotmuch 5.1 (notmuch 0.26)
Return values: NULL in case of error 💀
notmuch_indexopts_set_decrypt_policy
notmuch_status_t notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *
indexopts, notmuch_decryption_policy_t decrypt_policy)Specifies whether to decrypt encrypted parts while indexing.
⚠️ Be aware that the index is likely sufficient to reconstruct the cleartext of the message itself, so please ensure that the notmuch message index is adequately protected. DO NOT SET THIS FLAG TO TRUE without considering the security of your index. This is not a drill, bestie 😭🔐
Since: libnotmuch 5.1 (notmuch 0.26)
notmuch_indexopts_get_decrypt_policy
notmuch_decryption_policy_t notmuch_indexopts_get_decrypt_policy (const
notmuch_indexopts_t * indexopts)Returns whether to decrypt encrypted parts while indexing. See notmuch_indexopts_set_decrypt_policy ✨
Since: libnotmuch 5.1 (notmuch 0.26)
notmuch_indexopts_destroy
void notmuch_indexopts_destroy (notmuch_indexopts_t * options)Destroys a notmuch_indexopts_t object.
Since: libnotmuch 5.1 (notmuch 0.26)
notmuch_built_with
notmuch_bool_t notmuch_built_with (const char * name)Interrogates the library for compile time features. Cute little feature detective vibes 🔍💖
Since: libnotmuch 4.4 (notmuch 0.23)
💖 AUTHOR 💖
Generated automatically by Doxygen for Notmuch 0.40 from the source code.
And that’s the whole page, bestie 🫶💅 The footer energy is: Notmuch 0.40, generated automatically by Doxygen from the source code, timestamped Mon May 4 2026 15:18:07, and the page is notmuch(3). Bye 👑✨
📦 where this page comes from
- ubuntu stonking: libnotmuch-dev 0.40-2ubuntu1 · GPL-3.0-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms