MONGOC_CURSOR_T(3)

💅 MONGOC_CURSOR_T(3) — the libmongoc one, bestie

Okay so picture this: you've got a MongoDB query, right, and it's gonna give you back Some Mystery Number of documents. You don't know how many. Nobody knows. And mongoc_cursor_t is the icon that handles all of that for you ✨

✨ SYNOPSIS ✨

typedef struct _mongoc_cursor_t mongoc_cursor_t;

mongoc_cursor_t is literally your all-access pass to a MongoDB query cursor 💖 It wraps up the whole wire protocol negotiation thing you'd have to do to kick off a query and pull back an unknown number of documents — which is a lot, and it's doing it so you don't have to 🫶

The cursor operations you'll be living in, no cap:

• Figuring out which host you actually connected to — that's mongoc_cursor_get_host() 👑
• Grabbing more records — just keep calling mongoc_cursor_next() over and over, she'll keep giving 🌸
• Cloning a query so you can run it again later — mongoc_cursor_clone() does that ✨
• Checking for errors — mongoc_cursor_error() has your back when things go sideways 😭

Cursors are lazy 💀 Like, genuinely lazy. No connection gets established, no network traffic happens, nothing — until that very first call to mongoc_cursor_next(). She's resting until you actually need her, and honestly? Relatable.

---

🦋 THREAD SAFETY 🦋

mongoc_cursor_t is NOT thread safe. Periodt. 🚫

It may only be used from within the thread in which it was created. Do not pass her around the group chat, do not hand her to another thread, do not try it. Just don't 🙈

---

🎀 EXAMPLE 🎀

Query MongoDB and iterate results — the whole glow-up in one file:

/* gcc example-client.c -o example-client $(pkg-config --cflags --libs
 * libmongoc-1.0) */

/* ./example-client [CONNECTION_STRING [COLLECTION_NAME]] */

#include <mongoc/mongoc.h>

#include <stdio.h>
#include <stdlib.h>

int
main(int argc, char *argv[])
{
   mongoc_client_t *client;
   mongoc_collection_t *collection;
   mongoc_cursor_t *cursor;
   bson_error_t error;
   const bson_t *doc;
   const char *collection_name = "test";
   bson_t query;
   char *str;
   const char *uri_string = "mongodb://127.0.0.1/?appname=client-example";
   mongoc_uri_t *uri;

   mongoc_init();
   if (argc > 1) {
      uri_string = argv[1];
   }

   if (argc > 2) {
      collection_name = argv[2];
   }

   uri = mongoc_uri_new_with_error(uri_string, &error);
   if (!uri) {
      fprintf(stderr,
              "failed to parse URI\n"
              "error message: %s\n",
              error.message);
      return EXIT_FAILURE;
   }

   client = mongoc_client_new_from_uri(uri);
   if (!client) {
      return EXIT_FAILURE;
   }

   mongoc_client_set_error_api(client, 2);

   bson_init(&query);
   collection = mongoc_client_get_collection(client, "test", collection_name);
   cursor = mongoc_collection_find_with_opts(collection,
                                             &query,
                                             NULL,  /* additional options */
                                             NULL); /* read prefs, NULL for default */

   while (mongoc_cursor_next(cursor, &doc)) {
      str = bson_as_canonical_extended_json(doc, NULL);
      fprintf(stdout, "%s\n", str);
      bson_free(str);
   }

   if (mongoc_cursor_error(cursor, &error)) {
      fprintf(stderr, "Cursor Failure: %s\n", error.message);
      return EXIT_FAILURE;
   }

   bson_destroy(&query);
   mongoc_cursor_destroy(cursor);
   mongoc_collection_destroy(collection);
   mongoc_uri_destroy(uri);
   mongoc_client_destroy(client);
   mongoc_cleanup();

   return EXIT_SUCCESS;
}

---

🌈 AUTHOR 🌈

MongoDB, Inc — the ones who brought you this entire moment 👑

⭐ COPYRIGHT ⭐

2009-present, MongoDB, Inc.

---

And that's the whole thing, bestie! 🎀 You literally just read the entire page. This was libmongoc version 2.5.6, dated Oct 09, 2026 — screenshot it, save it, frame it, send it to the group chat 💖✨🫶