diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-16 20:30:07 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-16 20:30:07 +0000 |
commit | 78c8bbc4157d577c291b289602794ecd1ff24c42 (patch) | |
tree | 288be46fb3bd79e6a7bf01ee90a17b6511cd1b99 /doc/gdbm.texinfo | |
parent | 979486e1b46a894fc9de2abe6eb8985536a5013c (diff) | |
download | gdbm-78c8bbc4157d577c291b289602794ecd1ff24c42.tar.gz gdbm-78c8bbc4157d577c291b289602794ecd1ff24c42.tar.bz2 |
Provide support for a simplified "define" construct.
* doc/gdbm.texinfo: Document the "define" statement.
* src/datconv.c: Support short and ushort data types.
* src/gdbmtool.c: Don't call checkdb prior to handling
the "hash" command.
* src/gram.y: Support simplified definition construct:
"define key|content type".
Diffstat (limited to 'doc/gdbm.texinfo')
-rw-r--r-- | doc/gdbm.texinfo | 140 |
1 files changed, 137 insertions, 3 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo index d5bb7f3..00acc41 100644 --- a/doc/gdbm.texinfo +++ b/doc/gdbm.texinfo @@ -1959,3 +1959,3 @@ command sets the @samp{delim2} variable to @samp{;} and the @example -srt delim2=";" noconfirm +set delim2=";" noconfirm @end example @@ -1967,4 +1967,4 @@ variable. Unless explicitly described in the discussion of the variables above, unsetting a boolean variable is equivalent to setting it to -@samp{false}. Unsetting a string variable is equivalent to setting it -to an empty string. +@samp{false}. Unsetting a string variable is equivalent to assigning it +an empty string. @end deffn @@ -2127,2 +2127,136 @@ Print the version of @command{gdbm}. @subsection Data Definitions +GDBM databases are able to keep data of any type, both in the key and +in the content part of a record. Quite often these data are +structured, i.e. they consist of several fields of various types. +@command{Gdbmtool} provides a mechanism for handling such kind of +records. + +The @code{define} command defines a record structure. The general +syntax is: + +@example +define @var{what} @var{definition} +@end example + +@noindent +where @var{what} is @samp{key} to defining the structure of key data and +@samp{content} to define the structure of the content records. + +The @var{definition} can be of two distinct formats. In the simplest +case it is a single data type. For example, + +@example +define content int +@end example + +@noindent +defines content records consisting of a single integer field. +Supported data types are: + +@table @asis +@item char +Single byte (signed). +@item short +Signed short integer. +@item ushort +Unsigned short integer. +@item int +Signed integer. +@item unsigned +@itemx uint +Unsigned integer. +@item long +Signed long integer. +@item ulong +Unsigned long integer. +@item llong +Signed long long integer. +@item ullong +Unsigned long long integer. +@item float +A float. +@item double +A double. +@item string +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 +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: + +@enumerate 1 +@item @code{define key string} +@item @code{define key zstring} +@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. + +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 +multiline and is terminated with the closing curly brace. For +example: + +@example +define content @{ + int status, + pad 8, + char id[3], + string name +@} +@end example + +@noindent +This defines a structure consisting of three members: an integer +@code{status}, an array of 8 bytes @code{id}, and a null-terminated +string @code{name}. Notice the @code{pad} statement: it allows to +introduce padding between structure members. Another useful statement +is @code{offset}: it specifies that the member following it begins at +the given offset in the structure. Assuming the size of @code{int} is +8 bytes, the above definition can also be written as + +@example +define content @{ + int status, + offset 16, + char id[3], + string name +@} +@end example + +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: + +@example +gdbmtool> fetch foo +status=2,id=@{ a, u, x @},name="quux" +@end example + +To supply a structured datum as an argument to a @command{gdbmtool} +command, use the same notation, but without field names, e.g.: + +@example +gdbmtool> hash @{ 2, @{a,u,x@}, "quux" @} +hash value = 13089969. +@end example |