docs: Added All NetBSD Manuals

1 files changed, 335 insertions, 0 deletions

diff --git a/static/netbsd/man3/sqlite3_open.3 b/static/netbsd/man3/sqlite3_open.3
new file mode 100644
index 00000000..63581d34
--- /dev/null
+++ b/static/netbsd/man3/sqlite3_open.3
@@ -0,0 +1,335 @@
+.Dd January 24, 2024
+.Dt SQLITE3_OPEN 3
+.Os
+.Sh NAME
+.Nm sqlite3_open ,
+.Nm sqlite3_open16 ,
+.Nm sqlite3_open_v2
+.Nd opening a new database connection
+.Sh SYNOPSIS
+.In sqlite3.h
+.Ft int
+.Fo sqlite3_open
+.Fa "const char *filename"
+.Fa "sqlite3 **ppDb"
+.Fc
+.Ft int
+.Fo sqlite3_open16
+.Fa "const void *filename"
+.Fa "sqlite3 **ppDb"
+.Fc
+.Ft int
+.Fo sqlite3_open_v2
+.Fa "const char *filename"
+.Fa "sqlite3 **ppDb"
+.Fa "int flags"
+.Fa "const char *zVfs"
+.Fc
+.Sh DESCRIPTION
+These routines open an SQLite database file as specified by the filename
+argument.
+The filename argument is interpreted as UTF-8 for sqlite3_open() and
+sqlite3_open_v2() and as UTF-16 in the native byte order for sqlite3_open16().
+A database connection handle is usually returned
+in *ppDb, even if an error occurs.
+The only exception is that if SQLite is unable to allocate memory to
+hold the sqlite3 object, a NULL will be written into *ppDb instead
+of a pointer to the sqlite3 object.
+If the database is opened (and/or created) successfully, then SQLITE_OK
+is returned.
+Otherwise an error code is returned.
+The
+.Fn sqlite3_errmsg
+or
+.Fn sqlite3_errmsg16
+routines can be used to obtain an English language description of the
+error following a failure of any of the sqlite3_open() routines.
+.Pp
+The default encoding will be UTF-8 for databases created using sqlite3_open()
+or sqlite3_open_v2().
+The default encoding for databases created using sqlite3_open16() will
+be UTF-16 in the native byte order.
+.Pp
+Whether or not an error occurs when it is opened, resources associated
+with the database connection handle should be released
+by passing it to
+.Fn sqlite3_close
+when it is no longer required.
+.Pp
+The sqlite3_open_v2() interface works like sqlite3_open() except that
+it accepts two additional parameters for additional control over the
+new database connection.
+The flags parameter to sqlite3_open_v2() must include, at a minimum,
+one of the following three flag combinations:
+.Bl -tag -width Ds
+.It SQLITE_OPEN_READONLY
+The database is opened in read-only mode.
+If the database does not already exist, an error is returned.
+.It SQLITE_OPEN_READWRITE
+The database is opened for reading and writing if possible, or reading
+only if the file is write protected by the operating system.
+In either case the database must already exist, otherwise an error
+is returned.
+For historical reasons, if opening in read-write mode fails due to
+OS-level permissions, an attempt is made to open it in read-only mode.
+.Fn sqlite3_db_readonly
+can be used to determine whether the database is actually read-write.
+.It SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
+The database is opened for reading and writing, and is created if it
+does not already exist.
+This is the behavior that is always used for sqlite3_open() and sqlite3_open16().
+.El
+.Pp
+In addition to the required flags, the following optional flags are
+also supported:
+.Bl -tag -width Ds
+.It SQLITE_OPEN_URI
+The filename can be interpreted as a URI if this flag is set.
+.It SQLITE_OPEN_MEMORY
+The database will be opened as an in-memory database.
+The database is named by the "filename" argument for the purposes of
+cache-sharing, if shared cache mode is enabled, but the "filename"
+is otherwise ignored.
+.It SQLITE_OPEN_NOMUTEX
+The new database connection will use the "multi-thread" threading mode.
+This means that separate threads are allowed to use SQLite at the same
+time, as long as each thread is using a different database connection.
+.It SQLITE_OPEN_FULLMUTEX
+The new database connection will use the "serialized" threading mode.
+This means the multiple threads can safely attempt to use the same
+database connection at the same time.
+(Mutexes will block any actual concurrency, but in this mode there
+is no harm in trying.)
+.It SQLITE_OPEN_SHAREDCACHE
+The database is opened shared cache enabled, overriding
+the default shared cache setting provided by
+.Fn sqlite3_enable_shared_cache .
+The use of shared cache mode is discouraged
+and hence shared cache capabilities may be omitted from many builds
+of SQLite.
+In such cases, this option is a no-op.
+.It SQLITE_OPEN_PRIVATECACHE
+The database is opened shared cache disabled, overriding
+the default shared cache setting provided by
+.Fn sqlite3_enable_shared_cache .
+.It SQLITE_OPEN_EXRESCODE
+The database connection comes up in "extended result code mode".
+In other words, the database behaves has if sqlite3_extended_result_codes(db,1)
+where called on the database connection as soon as the connection is
+created.
+In addition to setting the extended result code mode, this flag also
+causes
+.Fn sqlite3_open_v2
+to return an extended result code.
+.It SQLITE_OPEN_NOFOLLOW
+The database filename is not allowed to contain a symbolic link
+.El
+.Pp
+If the 3rd parameter to sqlite3_open_v2() is not one of the required
+combinations shown above optionally combined with other SQLITE_OPEN_* bits
+then the behavior is undefined.
+Historic versions of SQLite have silently ignored surplus bits in the
+flags parameter to sqlite3_open_v2(), however that behavior might not
+be carried through into future versions of SQLite and so applications
+should not rely upon it.
+Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op for
+sqlite3_open_v2().
+The SQLITE_OPEN_EXCLUSIVE does *not* cause the open to fail if the
+database already exists.
+The SQLITE_OPEN_EXCLUSIVE flag is intended for use by the VFS interface
+only, and not by sqlite3_open_v2().
+.Pp
+The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs
+object that defines the operating system interface that the new database
+connection should use.
+If the fourth parameter is a NULL pointer then the default sqlite3_vfs
+object is used.
+.Pp
+If the filename is ":memory:", then a private, temporary in-memory
+database is created for the connection.
+This in-memory database will vanish when the database connection is
+closed.
+Future versions of SQLite might make use of additional special filenames
+that begin with the ":" character.
+It is recommended that when a database filename actually does begin
+with a ":" character you should prefix the filename with a pathname
+such as "./" to avoid ambiguity.
+.Pp
+If the filename is an empty string, then a private, temporary on-disk
+database will be created.
+This private database will be automatically deleted as soon as the
+database connection is closed.
+.Ss URI Filenames
+If URI filename interpretation is enabled, and the filename
+argument begins with "file:", then the filename is interpreted as a
+URI.
+URI filename interpretation is enabled if the SQLITE_OPEN_URI
+flag is set in the third argument to sqlite3_open_v2(), or if it has
+been enabled globally using the SQLITE_CONFIG_URI
+option with the
+.Fn sqlite3_config
+method or by the SQLITE_USE_URI compile-time option.
+URI filename interpretation is turned off by default, but future releases
+of SQLite might enable URI filename interpretation by default.
+See "URI filenames" for additional information.
+.Pp
+URI filenames are parsed according to RFC 3986.
+If the URI contains an authority, then it must be either an empty string
+or the string "localhost".
+If the authority is not an empty string or "localhost", an error is
+returned to the caller.
+The fragment component of a URI, if present, is ignored.
+.Pp
+SQLite uses the path component of the URI as the name of the disk file
+which contains the database.
+If the path begins with a '/' character, then it is interpreted as
+an absolute path.
+If the path does not begin with a '/' (meaning that the authority section
+is omitted from the URI) then the path is interpreted as a relative
+path.
+On windows, the first component of an absolute path is a drive specification
+(e.g. "C:").
+.Pp
+The query component of a URI may contain parameters that are interpreted
+either by SQLite itself, or by a custom VFS implementation.
+SQLite and its built-in VFSes interpret the following query parameters:
+.Bl -bullet
+.It
+\fBvfs\fP: The "vfs" parameter may be used to specify the name of a VFS object
+that provides the operating system interface that should be used to
+access the database file on disk.
+If this option is set to an empty string the default VFS object is
+used.
+Specifying an unknown VFS is an error.
+If sqlite3_open_v2() is used and the vfs option is present, then the
+VFS specified by the option takes precedence over the value passed
+as the fourth parameter to sqlite3_open_v2().
+.It
+\fBmode\fP: The mode parameter may be set to either "ro", "rw", "rwc", or
+"memory".
+Attempting to set it to any other value is an error.
+If "ro" is specified, then the database is opened for read-only access,
+just as if the SQLITE_OPEN_READONLY flag had been
+set in the third argument to sqlite3_open_v2().
+If the mode option is set to "rw", then the database is opened for
+read-write (but not create) access, as if SQLITE_OPEN_READWRITE (but
+not SQLITE_OPEN_CREATE) had been set.
+Value "rwc" is equivalent to setting both SQLITE_OPEN_READWRITE and
+SQLITE_OPEN_CREATE.
+If the mode option is set to "memory" then a pure in-memory database
+that never reads or writes from disk is used.
+It is an error to specify a value for the mode parameter that is less
+restrictive than that specified by the flags passed in the third parameter
+to sqlite3_open_v2().
+.It
+\fBcache\fP: The cache parameter may be set to either "shared" or "private".
+Setting it to "shared" is equivalent to setting the SQLITE_OPEN_SHAREDCACHE
+bit in the flags argument passed to sqlite3_open_v2().
+Setting the cache parameter to "private" is equivalent to setting the
+SQLITE_OPEN_PRIVATECACHE bit.
+If sqlite3_open_v2() is used and the "cache" parameter is present in
+a URI filename, its value overrides any behavior requested by setting
+SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
+.It
+\fBpsow\fP: The psow parameter indicates whether or not the powersafe overwrite
+property does or does not apply to the storage media on which the database
+file resides.
+.It
+\fBnolock\fP: The nolock parameter is a boolean query parameter which if
+set disables file locking in rollback journal modes.
+This is useful for accessing a database on a filesystem that does not
+support locking.
+Caution:  Database corruption might result if two or more processes
+write to the same database and any one of those processes uses nolock=1.
+.It
+\fBimmutable\fP: The immutable parameter is a boolean query parameter that
+indicates that the database file is stored on read-only media.
+When immutable is set, SQLite assumes that the database file cannot
+be changed, even by a process with higher privilege, and so the database
+is opened read-only and all locking and change detection is disabled.
+Caution: Setting the immutable property on a database file that does
+in fact change can result in incorrect query results and/or SQLITE_CORRUPT
+errors.
+.El
+.Pp
+Specifying an unknown parameter in the query component of a URI is
+not an error.
+Future versions of SQLite might understand additional query parameters.
+See "query parameters with special meaning to SQLite"
+for additional information.
+.Ss URI filename examples
+.Pp
+   URI filenames   Results
+   file:data.db   Open the file "data.db" in the current directory.
+   file:/home/fred/data.db  file:///home/fred/data.db   file://localhost/home/fred/data.db
+  Open the database file "/home/fred/data.db".
+   file://darkstar/home/fred/data.db   An error.
+"darkstar" is not a recognized authority.
+   file:///C:/Documents%20and%20Settings/fred/Desktop/data.db   Windows
+only: Open the file "data.db" on fred's desktop on drive C:.
+Note that the %20 escaping in this example is not strictly necessary
+- space characters can be used literally in URI filenames.
+   file:data.db?mode=ro&cache=private   Open file "data.db" in the current
+directory for read-only access.
+Regardless of whether or not shared-cache mode is enabled by default,
+use a private cache.
+   file:/home/fred/data.db?vfs=unix-dotfile   Open file "/home/fred/data.db".
+Use the special VFS "unix-dotfile" that uses dot-files in place of
+posix advisory locking.
+   file:data.db?mode=readonly   An error.
+"readonly" is not a valid option for the "mode" parameter.
+Use "ro" instead:  "file:data.db?mode=ro".
+.Pp
+URI hexadecimal escape sequences (%HH) are supported within the path
+and query components of a URI.
+A hexadecimal escape sequence consists of a percent sign - "%" - followed
+by exactly two hexadecimal digits specifying an octet value.
+Before the path or query components of a URI filename are interpreted,
+they are encoded using UTF-8 and all hexadecimal escape sequences replaced
+by a single byte containing the corresponding octet.
+If this process generates an invalid UTF-8 encoding, the results are
+undefined.
+.Pp
+\fBNote to Windows users:\fP  The encoding used for the filename argument
+of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
+codepage is currently defined.
+Filenames containing international characters must be converted to
+UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2().
+.Pp
+\fBNote to Windows Runtime users:\fP  The temporary directory must be set
+prior to calling sqlite3_open() or sqlite3_open_v2().
+Otherwise, various features that require the use of temporary files
+may fail.
+.Pp
+.Sh IMPLEMENTATION NOTES
+These declarations were extracted from the
+interface documentation at line 3462.
+.Bd -literal
+SQLITE_API int sqlite3_open(
+  const char *filename,   /* Database filename (UTF-8) */
+  sqlite3 **ppDb          /* OUT: SQLite db handle */
+);
+SQLITE_API int sqlite3_open16(
+  const void *filename,   /* Database filename (UTF-16) */
+  sqlite3 **ppDb          /* OUT: SQLite db handle */
+);
+SQLITE_API int sqlite3_open_v2(
+  const char *filename,   /* Database filename (UTF-8) */
+  sqlite3 **ppDb,         /* OUT: SQLite db handle */
+  int flags,              /* Flags */
+  const char *zVfs        /* Name of VFS module to use */
+);
+.Ed
+.Sh SEE ALSO
+.Xr sqlite3 3 ,
+.Xr sqlite3_close 3 ,
+.Xr sqlite3_config 3 ,
+.Xr sqlite3_db_readonly 3 ,
+.Xr sqlite3_enable_shared_cache 3 ,
+.Xr sqlite3_errcode 3 ,
+.Xr sqlite3_temp_directory 3 ,
+.Xr sqlite3_vfs 3 ,
+.Xr SQLITE_CONFIG_SINGLETHREAD 3 ,
+.Xr SQLITE_IOCAP_ATOMIC 3 ,
+.Xr SQLITE_OK 3 ,
+.Xr SQLITE_OPEN_READONLY 3