2 files changed, 24 insertions, 4 deletions
diff --git a/src/printf.c b/src/printf.c
index 3fc4aca55..d412e5ee2 100644
--- a/src/printf.c
+++ b/src/printf.c
@@ -967,11 +967,21 @@ char *sqlite3StrAccumFinish(StrAccum *p){
   return p->zText;
 }
 
+/*
+** This singleton is an sqlite3_str object that is returned if
+** sqlite3_malloc() fails to provide space for a real one.  This
+** sqlite3_str object accepts no new text and always returns
+** an SQLITE_NOMEM error.
+*/
+static sqlite3_str sqlite3OomStr = {
+   0, 0, 0, 0, 0, SQLITE_NOMEM
+};
+
 /* Finalize a string created using sqlite3_str_new().
 */
 char *sqlite3_str_finish(sqlite3_str *p){
   char *z;
-  if( p ){
+  if( p!=0 && p!=&sqlite3OomStr ){
     z = sqlite3StrAccumFinish(p);
     sqlite3_free(p);
   }else{
@@ -1040,6 +1050,8 @@ sqlite3_str *sqlite3_str_new(sqlite3 *db){
   if( p ){
     sqlite3StrAccumInit(p, 0, 0, 0,
             db ? db->aLimit[SQLITE_LIMIT_LENGTH] : SQLITE_MAX_LENGTH);
+  }else{
+    p = &sqlite3OomStr;
   }
   return p;
 }
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index e2413d4d3..0cd06d09f 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -7155,12 +7155,20 @@ typedef struct sqlite3_str sqlite3_str;
 ** CONSTRUCTOR: sqlite3_str
 **
 ** ^The [sqlite3_str_new(D)] interface allocates and initializes
-** a new [sqlite3_str]
-** object.  ^The [sqlite3_str_new()] interface returns NULL on an out-of-memory
-** condition.  To avoid memory leaks, the object returned by
+** a new [sqlite3_str] object.  To avoid memory leaks, the object returned by
 ** [sqlite3_str_new()] must be freed by a subsequent call to 
 ** [sqlite3_str_finish(X)].
 **
+** ^The [sqlite3_str_new(D)] interface always returns a pointer to a
+** valid [sqlite3_str] object, though in the event of an out-of-memory
+** error the returned object might be a special singleton that will
+** silently reject new text, always return SQLITE_NOMEM from 
+** [sqlite3_str_errcode()], always return 0 for 
+** [sqlite3_str_length()], and always return NULL from
+** [sqlite3_str_finish(X)].  It is always safe to use the value
+** returned by [sqlite3_str_new(D)] as the sqlite3_str parameter
+** to any of the other [sqlite3_str] methods.
+**
 ** The D parameter to [sqlite3_str_new(D)] may be NULL.  If the
 ** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum
 ** length of the string contained in the [sqlite3_str] object will be