.\" Man page generated from reStructuredText.
.
.TH "MONGOC_CURSOR_T" "3" "Jun 04, 2021" "1.17.6" "libmongoc"
.SH NAME
mongoc_cursor_t \- mongoc_cursor_t
.
.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
..
.sp
Client\-side cursor abstraction
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct _mongoc_cursor_t mongoc_cursor_t;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBmongoc_cursor_t\fP provides access to a MongoDB query cursor.
It wraps up the wire protocol negotiation required to initiate a query and retrieve an unknown number of documents.
.sp
Common cursor operations include:
.INDENT 0.0
.IP \(bu 2
Determine which host we\(aqve connected to with \fBmongoc_cursor_get_host()\fP\&.
.IP \(bu 2
Retrieve more records with repeated calls to \fBmongoc_cursor_next()\fP\&.
.IP \(bu 2
Clone a query to repeat execution at a later point with \fBmongoc_cursor_clone()\fP\&.
.IP \(bu 2
Test for errors with \fBmongoc_cursor_error()\fP\&.
.UNINDENT
.sp
Cursors are lazy, meaning that no connection is established and no network traffic occurs until the first call to \fBmongoc_cursor_next()\fP\&.
.SH THREAD SAFETY
.sp
\fBmongoc_cursor_t\fP is \fINOT\fP thread safe. It may only be used from within the thread in which it was created.
.SH EXAMPLE
.sp
Query MongoDB and iterate results
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* 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: %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);

   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\en", str);
      bson_free (str);
   }

   if (mongoc_cursor_error (cursor, &error)) {
      fprintf (stderr, "Cursor Failure: %s\en", 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;
}

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