SYNOPSIS

          bool
          mongoc_collection_find_and_modify (mongoc_collection_t *collection,
                                             const bson_t *query,
                                             const bson_t *sort,
                                             const bson_t *update,
                                             const bson_t *fields,
                                             bool _remove,
                                             bool upsert,
                                             bool _new,
                                             bson_t *reply,
                                             bson_error_t *error);

PARAMETERS

       • collection: A mongoc_collection_t <>.

       • query:  A  bson_t  <https://www.mongoc.org/libbson/current/bson_t.html>  containing the query to locate
         target document(s).

       • sort: A bson_t  <https://www.mongoc.org/libbson/current/bson_t.html>  containing  the  sort  order  for
         query.

       • update: A bson_t <https://www.mongoc.org/libbson/current/bson_t.html> containing an update spec.

       • fields:  An  optional bson_t <https://www.mongoc.org/libbson/current/bson_t.html> containing the fields
         to return or NULL.

       • _remove: If the matching documents should be removed.

       • upsert: If an upsert should be performed.

       • _new: If the new version of the document should be returned.

       • reply: A maybe-NULL pointer to overwritable storage <https://www.mongodb.com/docs/languages/c/c-driver/
         current/libbson/guides/lifetimes/#overwritable-storage> for a  bson_t  <https://www.mongoc.org/libbson/
         current/bson_t.html> to contain the results.

       • error: An optional location for a bson_error_t <> or NULL.

DESCRIPTION

       Update and return an object.

       This is a thin wrapper around the findAndModify command. Either update or _remove arguments are required.

       As of MongoDB 3.2, the mongoc_write_concern_t <> specified on the mongoc_collection_t <> will be used, if
       any.

       reply  is  always  initialized,  and  must  be freed with bson_destroy() <https://www.mongoc.org/libbson/
       current/bson_destroy.html>.

       On success, the output reply contains the full server reply to the findAndModify command. See the MongoDB
       Manual  page  for  findAndModify   <https://www.mongodb.com/docs/manual/reference/command/findAndModify/#
       output> for the expected server reply.

ERRORS

       Errors are propagated via the error parameter.

RETURNS

       If  given  invalid  arguments  or a server/network error occurs, returns false and sets error. Otherwise,
       succeeds and returns true.  A write concern timeout or write concern error is considered a failure.

       See also:
          mongoc_collection_find_and_modify_with_opts() <>.

EXAMPLE

       find-and-modify.c

          #include <mongoc/mongoc.h>

          #include <stdio.h>

          int
          main(void)
          {
             mongoc_collection_t *collection;
             mongoc_client_t *client;
             const char *uri_string = "mongodb://127.0.0.1:27017/?appname=find-and-modify-example";
             mongoc_uri_t *uri;
             bson_error_t error;
             bson_t *query;
             bson_t *update;
             bson_t reply;
             char *str;

             mongoc_init();

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

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

             mongoc_client_set_error_api(client, 2);
             collection = mongoc_client_get_collection(client, "test", "test");

             /*
              * Build our query, {"cmpxchg": 1}
              */
             query = BCON_NEW("cmpxchg", BCON_INT32(1));

             /*
              * Build our update. {"$set": {"cmpxchg": 2}}
              */
             update = BCON_NEW("$set", "{", "cmpxchg", BCON_INT32(2), "}");

             /*
              * Submit the findAndModify.
              */
             if (!mongoc_collection_find_and_modify(collection, query, NULL, update, NULL, false, false, true, &reply, &error)) {
                fprintf(stderr, "find_and_modify() failure: %s\n", error.message);
                return EXIT_FAILURE;
             }

             /*
              * Print the result as JSON.
              */
             str = bson_as_canonical_extended_json(&reply, NULL);
             printf("%s\n", str);
             bson_free(str);

             /*
              * Cleanup.
              */
             bson_destroy(query);
             bson_destroy(update);
             bson_destroy(&reply);
             mongoc_collection_destroy(collection);
             mongoc_uri_destroy(uri);
             mongoc_client_destroy(client);

             mongoc_cleanup();

             return EXIT_SUCCESS;
          }

Author

       MongoDB, Inc

Copyright

       2009-present, MongoDB, Inc.

2.2.1                                             Dec 11, 2025              MONGOC_COLLECTION_FIND_AND_MODIFY(3)