13 Export and Import

Gdbm databases can be converted into so-called flat format files. Such files cannot be used for searching, their sole purpose is to keep the data from the database for restoring it when the need arrives. There are two flat file formats, which differ in the way they represent the data and in the amount of meta-information stored. Both formats can be used, for example, to migrate between the different versions of gdbm databases. Generally speaking, flat files are safe to send over the network, and can be used to recreate the database on another machine. The recreated database is guaranteed to be a byte-to-byte equivalent of the database from which the flat file was created. This does not necessarily mean, however, that this file can be used in the same way as the original one. For example, if the original database contained non-ASCII data (e.g. C structures, integers etc.), the recreated database can be of any use only if the target machine has the same integer size and byte ordering as the source one and if its C compiler uses the same packing conventions as the one which generated C which populated the original database. In general, such binary databases are not portable between machines, unless you follow some stringent rules on what data is written to them and how it is interpreted.

The GDBM version 1.11 supports two flat file formats. The binary flat file format was first implemented in GDBM version 1.9.1. This format stores only key/data pairs, it does not keep information about the database file itself. As its name implies, files in this format are binary files.

The ascii flat file format encodes all data in base64 and stores not only key/data pairs, but also the original database file metadata, such as file name, mode and ownership. Files in this format can be sent without additional encapsulation over transmission channels that normally allow only ASCII data, such as, e.g. SMTP. Due to additional metadata they allow for restoring an exact copy of the database, including file ownership and privileges, which is especially important if the database in question contained some security-related data.

We call a process of creating a flat file from a database exporting or dumping this database. The reverse process, creating the database from a flat file is called importing or loading the database.

gdbm interface: int gdbm_dump (GDBM_FILE dbf, const char *filename, int format, int open_flags, int mode)

Dumps the database file to the named file in requested format. Arguments are:

dbf

A pointer to the source database, returned by a prior call to gdbm_open.

filename

Name of the dump file.

format

Output file format. Allowed values are: ‘GDBM_DUMP_FMT_BINARY’ to create a binary dump and ‘GDBM_DUMP_FMT_ASCII’ to create an ASCII dump file.

open_flags

How to create the output file. If flag is ‘GDBM_WRCREAT’ the file will be created if it does not exist. If it does exist, the gdbm_dump will fail.

If flag is ‘GDBM_NEWDB’, the function will create a new output file, replacing it if it already exists.

mode

The permissions to use when creating the output file. See http://www.manpagez.com/man/2/open, for a detailed discussion.

gdbm interface: int gdbm_load (GDBM_FILE *pdbf, const char *filename, int flag, int meta_mask, unsigned long *errline)

Loads data from the dump file filename into the database pointed to by pdbf. The latter can point to ‘NULL’, in which case the function will try to create a new database. If it succeeds, the function will return, in the memory location pointed to by pdbf, a pointer to the newly created database. If the dump file carries no information about the original database file name, the function will set gdbm_errno to ‘GDBM_NO_DBNAME’ and return ‘-1’, indicating failure.

The flag has the same meaning as the flag argument to the gdbm_store function (see section Inserting and replacing records in the database.).

The meta_mask argument can be used to disable restoring certain bits of file’s meta-data from the information in the input dump file. It is a binary OR of zero or more of the following:

GDBM_META_MASK_MODE: Do not restore file mode.
GDBM_META_MASK_OWNER: Do not restore file owner.

The function returns 0 upon successful completion or -1 on fatal errors and 1 on mild (non-fatal) errors.

If a fatal error occurs, gdbm_errno will be set to one of the following values:

GDBM_FILE_OPEN_ERROR: Input file (filename) cannot be opened. The errno variable can be used to get more detail about the failure.
GDBM_MALLOC_ERROR: Not enough memory to load data.
GDBM_FILE_READ_ERROR: Reading from filename failed. The errno variable can be used to get more detail about the failure.
GDBM_ILLEGAL_DATA: Input contained some illegal data.
GDBM_ITEM_NOT_FOUND: This error can occur only when the input file is in ASCII format. It 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 ‘GDBM_ILLEGAL_DATA’.

Mild errors mean that the function was able to successfully load and restore the data, but was unable to change database file metadata afterward. The table below lists possible values for gdbm_errno in this case. To get more detail, inspect the system errno variable.

GDBM_ERR_FILE_OWNER: The function was unable to restore database file owner.
GDBM_ERR_FILE_MODE: The function was unable to restore database file mode (permission bits).

If an error occurs while loading data from an input file in ASCII format, the number of line in which the error occurred will be stored in the location pointed to by the errline parameter, unless it is ‘NULL’.

If the line information is not available or applicable, errline will be set to ‘0’.

gdbm interface: int gdbm_dump_to_file (GDBM_FILE dbf, FILE *fp, int format)

This is an alternative entry point to gdbm_dump (which see). Arguments are:

dbf: A pointer to the source database, returned by a call to gdbm_open.
fp: File to write the data to.
format: Format of the dump file. See the format argument to the gdbm_dump function.

gdbm interface: int gdbm_load_from_file (GDBM_FILE *pdbf, FILE *fp, int replace, int meta_mask, unsigned long *line): This is an alternative entry point to gdbm_dump. It writes the output to fp which must be a file open for writing. The rest of arguments is the same as for gdbm_load (excepting of course flag, which is not needed in this case).

gdbm interface: int gdbm_export (GDBM_FILE dbf, const char *exportfile, int flag, int mode)

This function is retained for compatibility with GDBM 1.10 and earlier. It dumps the database to a file in binary dump format and is entirely equivalent to

gdbm_dump(dbf, exportfile, GDBM_DUMP_FMT_BINARY,
          flag, mode)

gdbm interface: int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp): This is an alternative entry point to gdbm_export. This function writes to file fp a binary dump of the database dbf.

gdbm interface: int gdbm_import (GDBM_FILE dbf, const char *importfile, int flag)

This function is retained for compatibility with GDBM 1.10 and earlier. It loads the file importfile, which must be a binary flat file, into the database dbf and is equivalent to the following construct:

dbf = gdbm_open (importfile, 0,
                       flag == GDBM_REPLACE ?
                         GDBM_WRCREAT : GDBM_NEWDB,
                       0600, NULL);
gdbm_load (&dbf, exportfile, 0, flag, NULL)

gdbm interface: int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag)

An alternative entry point to gdbm_import. Reads the binary dump from the file fp and stores the key/value pairs to dbf. See section Inserting and replacing records in the database., for a description of flag.

This function is equivalent to:

dbf = gdbm_open (importfile, 0,
                       flag == GDBM_REPLACE ?
                         GDBM_WRCREAT : GDBM_NEWDB,
                       0600, NULL);
gdbm_load_from_file (dbf, fp, flag, 0, NULL);

This document was generated on January 24, 2014 using texi2html 5.0.