aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2013-05-16 20:30:07 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2013-05-16 20:30:07 +0000
commit78c8bbc4157d577c291b289602794ecd1ff24c42 (patch)
tree288be46fb3bd79e6a7bf01ee90a17b6511cd1b99 /doc
parent979486e1b46a894fc9de2abe6eb8985536a5013c (diff)
downloadgdbm-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')
-rw-r--r--doc/gdbm.texinfo140
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
@@ -1957,7 +1957,7 @@ command sets the @samp{delim2} variable to @samp{;} and the
1957@samp{confirm} variable to @samp{false}: 1957@samp{confirm} variable to @samp{false}:
1958 1958
1959@example 1959@example
1960srt delim2=";" noconfirm 1960set delim2=";" noconfirm
1961@end example 1961@end example
1962@end deffn 1962@end deffn
1963 1963
@@ -1965,8 +1965,8 @@ srt delim2=";" noconfirm
1965Unsets the listed variables. The effect of unsetting depends on the 1965Unsets the listed variables. The effect of unsetting depends on the
1966variable. Unless explicitly described in the discussion of the 1966variable. Unless explicitly described in the discussion of the
1967variables above, unsetting a boolean variable is equivalent to setting it to 1967variables above, unsetting a boolean variable is equivalent to setting it to
1968@samp{false}. Unsetting a string variable is equivalent to setting it 1968@samp{false}. Unsetting a string variable is equivalent to assigning it
1969to an empty string. 1969an empty string.
1970@end deffn 1970@end deffn
1971 1971
1972@node commands 1972@node commands
@@ -2125,6 +2125,140 @@ Print the version of @command{gdbm}.
2125 2125
2126@node definitions 2126@node definitions
2127@subsection Data Definitions 2127@subsection Data Definitions
2128GDBM databases are able to keep data of any type, both in the key and
2129in the content part of a record. Quite often these data are
2130structured, i.e. they consist of several fields of various types.
2131@command{Gdbmtool} provides a mechanism for handling such kind of
2132records.
2133
2134The @code{define} command defines a record structure. The general
2135syntax is:
2136
2137@example
2138define @var{what} @var{definition}
2139@end example
2140
2141@noindent
2142where @var{what} is @samp{key} to defining the structure of key data and
2143@samp{content} to define the structure of the content records.
2144
2145The @var{definition} can be of two distinct formats. In the simplest
2146case it is a single data type. For example,
2147
2148@example
2149define content int
2150@end example
2151
2152@noindent
2153defines content records consisting of a single integer field.
2154Supported data types are:
2155
2156@table @asis
2157@item char
2158Single byte (signed).
2159@item short
2160Signed short integer.
2161@item ushort
2162Unsigned short integer.
2163@item int
2164Signed integer.
2165@item unsigned
2166@itemx uint
2167Unsigned integer.
2168@item long
2169Signed long integer.
2170@item ulong
2171Unsigned long integer.
2172@item llong
2173Signed long long integer.
2174@item ullong
2175Unsigned long long integer.
2176@item float
2177A float.
2178@item double
2179A double.
2180@item string
2181Null-terminated string, trailing null being part of the string.
2182@item zstring
2183A string of characters without the terminating null.
2184@end table
2185
2186All numeric data types (integer as well as floating point) have the
2187same respective widths as in C language on the host where the database
2188file resides.
2189
2190The @samp{string} and @samp{zstring} are special. Both define a
2191string of bytes, similar to @samp{char x[]} in C. The former
2192defines a null-terminated string, the latter - a string without null
2193terminator. This makes difference when the string is the only part of
2194datum. Consider the following two definitions:
2195
2196@enumerate 1
2197@item @code{define key string}
2198@item @code{define key zstring}
2199@end enumerate
2200
2201@noindent
2202Now, suppose we want to store the string "ab" in the key. Using the
2203definition (1), the @code{dptr} member of GDBM @code{datum} will
2204contain three bytes: @samp{a}, @samp{b}, and ASCII 0. The
2205@code{dsize} member will have the value 3. Using the definition (2),
2206the @code{dptr} member will contain two bytes: @samp{a} and @samp{b},
2207and the @code{dsize} member will have the value 2.
2208
2209The second form of the @code{define} statement is similar to the C
2210@code{struct} statement and allows for defining structural data. In
2211this form, the @var{definition} part is a comma-separated list of data
2212types and variables enclosed in curly braces. In contrast to the
2213rest of @command{gdbm} commands, this command is inherently
2214multiline and is terminated with the closing curly brace. For
2215example:
2216
2217@example
2218define content @{
2219 int status,
2220 pad 8,
2221 char id[3],
2222 string name
2223@}
2224@end example
2225
2226@noindent
2227This defines a structure consisting of three members: an integer
2228@code{status}, an array of 8 bytes @code{id}, and a null-terminated
2229string @code{name}. Notice the @code{pad} statement: it allows to
2230introduce padding between structure members. Another useful statement
2231is @code{offset}: it specifies that the member following it begins at
2232the given offset in the structure. Assuming the size of @code{int} is
22338 bytes, the above definition can also be written as
2234
2235@example
2236define content @{
2237 int status,
2238 offset 16,
2239 char id[3],
2240 string name
2241@}
2242@end example
2243
2244When displaying the structured data, @command{gdbmtool} precedes each
2245value with the corresponding field name and delimits parts of the
2246structure with the string defined in the @samp{delim1} variable
2247(@pxref{variables}). Array elements are delimited using the string from
2248@samp{delim2}. For example:
2249
2250@example
2251gdbmtool> fetch foo
2252status=2,id=@{ a, u, x @},name="quux"
2253@end example
2254
2255To supply a structured datum as an argument to a @command{gdbmtool}
2256command, use the same notation, but without field names, e.g.:
2257
2258@example
2259gdbmtool> hash @{ 2, @{a,u,x@}, "quux" @}
2260hash value = 13089969.
2261@end example
2128 2262
2129@node startup files 2263@node startup files
2130@subsection Startup Files 2264@subsection Startup Files

Return to:

Send suggestions and report system problems to the System administrator.