aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2013-05-17 08:38:57 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2013-05-17 08:38:57 +0000
commitc7f543a57fc4feb9abb8ce97ff857db9f20026c7 (patch)
treec4e2feb455f46bd456ef84d8c40700edc0f8680c /doc
parent78c8bbc4157d577c291b289602794ecd1ff24c42 (diff)
downloadgdbm-c7f543a57fc4feb9abb8ce97ff857db9f20026c7.tar.gz
gdbm-c7f543a57fc4feb9abb8ce97ff857db9f20026c7.tar.bz2
Update the docs.
* NEWS: Update. * doc/gdbm.texinfo: Update. * doc/gdbmtool.1: Document the "define" statement. * src/datconv.c: Rename string datatypes to reflect their meaning. (dsprint): Improve output presentation.
Diffstat (limited to 'doc')
-rw-r--r--doc/gdbm.texinfo51
-rw-r--r--doc/gdbmtool.187
2 files changed, 115 insertions, 23 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo
index 00acc41..0d58f64 100644
--- a/doc/gdbm.texinfo
+++ b/doc/gdbm.texinfo
@@ -770,13 +770,13 @@ indicates that the data part of the record about to be read lacked
length specification. Application developers are advised to treat
this error equally as @samp{GDBM_ILLEGAL_DATA}.
@end table
Mild errors mean that the function was able to successfully load and
restore the data, but was unable to change database file metadata
-afterwards. The table below lists possible values for @code{gdbm_errno}
+afterward. The table below lists possible values for @code{gdbm_errno}
in this case. To get more detail, inspect the system @code{errno} variable.
@table @asis
@kwindex GDBM_ERR_FILE_OWNER
@item GDBM_ERR_FILE_OWNER
The function was unable to restore database file owner.
@@ -2075,13 +2075,13 @@ variables:
@item open
The database access mode. @xref{openvar,, The @var{open} variable},
for a list of its values.
@item lock
Whether or not to lock the database. Default is @samp{on}.
@item mmap
-Use the memmory mapping. Default is @samp{on}.
+Use the memory mapping. Default is @samp{on}.
@item sync
Synchronize after each write. Default is @samp{off}.
@end table
@xref{open parameters}, for a detailed description of these variables.
@end deffn
@@ -2102,19 +2102,19 @@ Read @command{gdbmtool} commands from the file @var{filename}.
Print current program status. The following example shows the
information displayed:
@example
Database file: junk.gdbm
Database is open
-define key @{
- string,
-@}
-define content @{
- string,
-@}
+define key string
+define content string
@end example
+
+The two @samp{define} strings show the defined formats for key and
+content data. @xref{definitions}, for a detailed discussion of their
+meaning.
@end deffn
@deffn {command verb} store @var{key} @var{data}
Store the @var{data} with @var{key} in the database. If @var{key}
already exists, its data will be replaced.
@end deffn
@@ -2171,43 +2171,45 @@ Signed long integer.
Unsigned long integer.
@item llong
Signed long long integer.
@item ullong
Unsigned long long integer.
@item float
-A float.
+A floating point number.
@item double
-A double.
+Double-precision floating point number.
@item string
+Array of bytes.
+@item stringz
Null-terminated string, trailing null being part of the string.
-@item zstring
-A string of characters without the terminating null.
@end table
All numeric data types (integer as well as floating point) have the
same respective widths as in C language on the host where the database
file resides.
-The @samp{string} and @samp{zstring} are special. Both define a
+The @samp{string} and @samp{stringz} are special. Both define a
string of bytes, similar to @samp{char x[]} in C. The former
-defines a null-terminated string, the latter - a string without null
-terminator. This makes difference when the string is the only part of
-datum. Consider the following two definitions:
+defines an array of bytes, the latter - a null-terminated string.
+This makes a difference, in particular, when the string is the only
+part of datum. Consider the following two definitions:
@enumerate 1
@item @code{define key string}
-@item @code{define key zstring}
+@item @code{define key stringz}
@end enumerate
@noindent
Now, suppose we want to store the string "ab" in the key. Using the
definition (1), the @code{dptr} member of GDBM @code{datum} will
-contain three bytes: @samp{a}, @samp{b}, and ASCII 0. The
-@code{dsize} member will have the value 3. Using the definition (2),
-the @code{dptr} member will contain two bytes: @samp{a} and @samp{b},
-and the @code{dsize} member will have the value 2.
+contain two bytes: @samp{a}, and @samp{b}. Consequently, the
+@code{dsize} member will have the value 2. Using the definition (2),
+the @code{dptr} member will contain three bytes: @samp{a}, @samp{b},
+and ASCII 0. The @code{dsize} member will have the value 3.
+
+The definition (1) is the default for both key and content.
The second form of the @code{define} statement is similar to the C
@code{struct} statement and allows for defining structural data. In
this form, the @var{definition} part is a comma-separated list of data
types and variables enclosed in curly braces. In contrast to the
rest of @command{gdbm} commands, this command is inherently
@@ -2238,12 +2240,17 @@ define content @{
offset 16,
char id[3],
string name
@}
@end example
+@empth{NOTE}: The @samp{string} type can reasonably be used only if it
+is the last or the only member of the data structure. That's because it
+provides no information about the number of elements in the array, so
+it is interpreted to contain all bytes up to the end of the datum.
+
When displaying the structured data, @command{gdbmtool} precedes each
value with the corresponding field name and delimits parts of the
structure with the string defined in the @samp{delim1} variable
(@pxref{variables}). Array elements are delimited using the string from
@samp{delim2}. For example:
@@ -2279,13 +2286,13 @@ file in parentheses and defines the structure of the database content
records:
@example
@group
set quiet
set ps1="(%f) "
-
+define key stringz
define content @{
int time,
pad 4,
int status
@}
@end group
diff --git a/doc/gdbmtool.1 b/doc/gdbmtool.1
index 2326a32..a04fbef 100644
--- a/doc/gdbmtool.1
+++ b/doc/gdbmtool.1
@@ -10,13 +10,13 @@
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */
-.TH GDBM_DUMP 1 "May 9, 2013" "GDBM" "GDBM User Reference"
+.TH GDBM_DUMP 1 "May 17, 2013" "GDBM" "GDBM User Reference"
.SH NAME
gdbmtool \- examine and modify a GDBM database
.SH SYNOPSIS
\fBgdbmtool\fR [\fB\-lmNnqrs\fR] [\fB\-b\fR \fISIZE\fR] [\fB\-c\fR \fISIZE\fR]\
[\fB\-f\fR \fIFILE\fR] [\fB\-\-block\-size\fR=\fISIZE\fR]
[\fB\-\-cache\-size\fR=\fISIZE\fR] [\fB\-\-file\fR \fIFILE\fR]\
@@ -241,12 +241,97 @@ Store the \fIDATA\fR with the given \fIKEY\fR in the database. If the
Unsets listed variables.
.TP
.BR version
Print the version of
.BR gdbm .
.SH "DATA DEFINITIONS"
+The \fBdefine\fR statement provides a mechanism for defining key or
+content structures. It is similar to the \fBC\fR \fBstruct\fR
+declaration:
+.sp
+.nf
+.in +4
+\fBdefine\fR \fBkey\fR|\fBcontent\fR \fB{\fR \fIdefnlist\fR \fB}\fR
+.in
+.fi
+.PP
+The \fIdefnlist\fR is a comma-separated list of member declarations.
+Within \fIdefnlist\fR the newline character looses its special meaning
+as the command terminator, so each declaration can appear on a
+separate line and arbitrary number of comments can be inserted to
+document the definition.
+.PP
+Each declaration has one of the following formats
+.sp
+.nf
+.in +4
+\fItype\fR \fIname\fR
+\fItype\fR \fIname\fR \fB[\fIN\fB]\fR
+.in
+.fi
+.sp
+where \fItype\fR is a data type and \fIname\fR is the member name.
+The second format defines the member \fIname\fR as an array of \fIN\fR
+elements of \fItype\fR.
+.PP
+The supported types are:
+.sp
+.nf
+.ta 8n 20n
+.ul
+ type meaning
+ char single byte (signed)
+ short signed short integer
+ ushort unsigned short integer
+ int signed integer
+ unsigned unsigned integer
+ uint ditto
+ long signed long integer
+ ulong unsigned long integer
+ llong signed long long integer
+ ullong unsigned long long integer
+ float a floating point number
+ double double-precision floating point number
+ string array of characters (see the \fBNOTE\fR below)
+ stringz null-terminated string of characters
+.fi
+.PP
+The following alignment declarations can be used within \fIdefnlist\fR:
+.TP
+\fBoffset\fR \fIN\fR
+The next member begins at offset \fIN\fR.
+.TP
+\fBpad\fR \fIN\fR
+Add \fIN\fR bytes of padding to the previous member.
+.PP
+For example:
+.sp
+.nf
+.in +4
+\fBdefine content {
+ int status,
+ pad 8,
+ char id[3],
+ stringz name
+}\fR
+.fi
+.PP
+To define data consisting of a single data member, the following
+simplified construct can be used:
+.sp
+.nf
+.in +4
+\fBdefine\fR \fBkey\fR|\fBcontent\fR \fItype\fR
+.fi
+.PP
+where \fItype\fR is one of the types discussed above.
+.PP
+\fBNOTE\fR: The \fBstring\fR type can reasonably be used only if it is
+the last or the only member of the data structure. That's because it
+provides no information about the number of elements in the array, so
+it is interpreted to contain all bytes up to the end of the datum.
.SH VARIABLES
.TP
.BR confirm ", boolean"
Whether to ask for confirmation before certain destructive operations,
such as truncating the existing database. Default is
.BR true .

Return to:

Send suggestions and report system problems to the System administrator.