.\" Man page generated from reStructuredText.
.
.TH "MONGOC_COLLECTION_FIND_AND_MODIFY" "3" "Jun 04, 2021" "1.17.6" "libmongoc"
.SH NAME
mongoc_collection_find_and_modify \- mongoc_collection_find_and_modify()
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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);
.ft P
.fi
.UNINDENT
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.IP \(bu 2
\fBcollection\fP: A \fBmongoc_collection_t\fP\&.
.IP \(bu 2
\fBquery\fP: A \fI\%bson_t\fP containing the query to locate target document(s).
.IP \(bu 2
\fBsort\fP: A \fI\%bson_t\fP containing the sort order for \fBquery\fP\&.
.IP \(bu 2
\fBupdate\fP: A \fI\%bson_t\fP containing an update spec.
.IP \(bu 2
\fBfields\fP: An optional \fI\%bson_t\fP containing the fields to return or \fBNULL\fP\&.
.IP \(bu 2
\fB_remove\fP: If the matching documents should be removed.
.IP \(bu 2
\fBupsert\fP: If an upsert should be performed.
.IP \(bu 2
\fB_new\fP: If the new version of the document should be returned.
.IP \(bu 2
\fBreply\fP: Optional pointer to an \fIuninitialized\fP \fI\%bson_t\fP that will be initialized with the result.
.IP \(bu 2
\fBerror\fP: An optional location for a \fBbson_error_t\fP or \fBNULL\fP\&.
.UNINDENT
.SH DESCRIPTION
.sp
Update and return an object.
.sp
This is a thin wrapper around the \fBfindAndModify\fP command. Either \fBupdate\fP or \fB_remove\fP arguments are required.
.sp
See also: \fBmongoc_collection_find_and_modify_with_opts\fP\&.
.sp
As of MongoDB 3.2, the \fBmongoc_write_concern_t\fP specified on the \fBmongoc_collection_t\fP will be used, if any.
.sp
\fBreply\fP is always initialized, and must be freed with \fI\%bson_destroy()\fP\&.
.SH ERRORS
.sp
Errors are propagated via the \fBerror\fP parameter.
.SH RETURNS
.sp
Returns either the document before or after modification based on the \fB_new\fP parameter.
.sp
A write concern timeout or write concern error is considered a failure.
.SH EXAMPLE
.sp
find\-and\-modify.c
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <mongoc/mongoc.h>
#include <stdio.h>


int
main (int argc, char *argv[])
{
   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\en"
               "error message:       %s\en",
               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\en", error.message);
      return EXIT_FAILURE;
   }

   /*
    * Print the result as JSON.
    */
   str = bson_as_canonical_extended_json (&reply, NULL);
   printf ("%s\en", 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;
}

.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.