MONGOC_GRIDFS_BUCKET_T(3)

💅 MONGOC_GRIDFS_BUCKET_T(3) 💅

okay so this is the libmongoc page for mongoc_gridfs_bucket_t, and bestie, it's lowkey iconic — this is the gridfs type you actually want. pull up a chair. 🫶

---

✨ SYNOPSIS ✨

#include <mongoc/mongoc.h>

typedef struct _mongoc_gridfs_bucket_t mongoc_gridfs_bucket_t;

that's it. that's the whole vibe. one include, one opaque struct, infinite possibilities. 💅

---

🌸 DESCRIPTION 🌸

mongoc_gridfs_bucket_t gives you a spec-compliant MongoDB GridFS implementation — and yes, it's the one that supersedes mongoc_gridfs_t. so if you're out here still using the old one... no cap, it's giving legacy. 👀

for the full lore, go read the GridFS MongoDB documentation. iykyk. ✨

---

🦋 THREAD SAFETY 🦋

so important, putting it in its own section: mongoc_gridfs_bucket_t is NOT thread-safe. like, not even a little. 🙈

it should only ever be used in the same thread as the owning mongoc_client_t. periodt. don't be passing it around between threads and acting surprised when everything falls apart. 💀

---

🎀 LIFECYCLE 🎀

two rules, and they're giving main character energy:

• it is an error to free a mongoc_gridfs_bucket_t before you've freed all derived instances of mongoc_stream_t. clean up your streams first, bestie.
• the owning mongoc_client_t must outlive the mongoc_gridfs_bucket_t. the client is the parent here, the bucket does not outlive its parent. simple as. 🔥

fr fr, get the free order wrong and you're in undefined-behaviour territory. no cap.

---

🌈 EXAMPLE 🌈

here's example-gridfs-bucket.c — a whole little program that makes a bucket, uploads a file, downloads it, lists everything, deletes it, and cleans up. a full circle moment. ✨

#include <mongoc/mongoc.h>

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

int
main(int argc, char *argv[])
{
   const char *uri_string = "mongodb://localhost:27017/?appname=new-gridfs-example";
   mongoc_client_t *client;
   mongoc_database_t *db;
   mongoc_stream_t *file_stream;
   mongoc_gridfs_bucket_t *bucket;
   mongoc_cursor_t *cursor;
   bson_t filter;
   bool res;
   bson_value_t file_id;
   bson_error_t error;
   const bson_t *doc;
   char *str;
   mongoc_init();

   if (argc != 3) {
      fprintf(stderr, "usage: %s SOURCE_FILE_PATH FILE_COPY_PATH\n", argv[0]);
      return EXIT_FAILURE;
   }

   /* 1. Make a bucket. */
   client = mongoc_client_new(uri_string);
   db = mongoc_client_get_database(client, "test");
   bucket = mongoc_gridfs_bucket_new(db, NULL, NULL, &error);
   if (!bucket) {
      printf("Error creating gridfs bucket: %s\n", error.message);
      return EXIT_FAILURE;
   }

   /* 2. Insert a file.  */
   file_stream = mongoc_stream_file_new_for_path(argv[1], O_RDONLY, 0);
   res = mongoc_gridfs_bucket_upload_from_stream(bucket, "my-file", file_stream, NULL, &file_id, &error);
   if (!res) {
      printf("Error uploading file: %s\n", error.message);
      return EXIT_FAILURE;
   }

   mongoc_stream_close(file_stream);
   mongoc_stream_destroy(file_stream);

   /* 3. Download the file in GridFS to a local file. */
   file_stream = mongoc_stream_file_new_for_path(argv[2], O_CREAT | O_RDWR, 0);
   if (!file_stream) {
      perror("Error opening file stream");
      return EXIT_FAILURE;
   }

   res = mongoc_gridfs_bucket_download_to_stream(bucket, &file_id, file_stream, &error);
   if (!res) {
      printf("Error downloading file to stream: %s\n", error.message);
      return EXIT_FAILURE;
   }
   mongoc_stream_close(file_stream);
   mongoc_stream_destroy(file_stream);

   /* 4. List what files are available in GridFS. */
   bson_init(&filter);
   cursor = mongoc_gridfs_bucket_find(bucket, &filter, NULL);

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

   /* 5. Delete the file that we added. */
   res = mongoc_gridfs_bucket_delete_by_id(bucket, &file_id, &error);
   if (!res) {
      printf("Error deleting the file: %s\n", error.message);
      return EXIT_FAILURE;
   }

   /* 6. Cleanup. */
   mongoc_stream_close(file_stream);
   mongoc_stream_destroy(file_stream);
   mongoc_cursor_destroy(cursor);
   bson_destroy(&filter);
   mongoc_gridfs_bucket_destroy(bucket);
   mongoc_database_destroy(db);
   mongoc_client_destroy(client);
   mongoc_cleanup();

   return EXIT_SUCCESS;
}

the six steps are literally numbered in the comments so you cannot miss them: 1. make a bucket, 2. insert a file, 3. download it to a local file, 4. list what's in GridFS, 5. delete the file, 6. cleanup. ate and left no crumbs. 👑

---

🔍 SEE ALSO 🔍

• the MongoDB GridFS specification — the actual rules, go read them 📖
• the non spec-compliant mongoc_gridfs_t — the old one, for historical context 💀

---

👑 AUTHOR 👑

MongoDB, Inc

⭐ COPYRIGHT ⭐

2009-present, MongoDB, Inc.

---

and that's the page, bestie — libmongoc version 2.5.6, dated Oct 09, 2026. screenshot it, cite it, cite it in your PR description, go off. 🎀✨💖