(size_t)-1, assuming a 0-terminated string. The flags argument controls the encoding and is currently one of REP_UTF8 (string is UTF8 encoded), REP_MB (string is encoded in the current locale) or 0 (string is encoded in ISO latin 1). The string may, but is not required, to be closed by a full stop (.).

If parsing produces an exception the behaviour depends on the CVT_EXCEPTION flag. If present, the exception is propagated into the environment. Otherwise, the exception is placed in t and the return value is FALSE.^{212The CVT_EXCEPTION was added in version 8.3.12}.

12.4.8 BLOBS: Using atoms to store arbitrary binary data

SWI-Prolog atoms as well as strings can represent arbitrary binary data of arbitrary length. This facility is attractive for storing foreign data such as images in an atom. An atom is a unique handle to this data and the atom garbage collector is able to destroy atoms that are no longer referenced by the Prolog engine. This property of atoms makes them attractive as a handle to foreign resources, such as Java atoms, Microsoft's COM objects, etc., providing safe combined garbage collection.

To exploit these features safely and in an organised manner, the SWI-Prolog foreign interface allows creating‘atoms' with additional type information. The type is represented by a structure holding C function pointers that tell Prolog how to handle releasing the atom, writing it, sorting it, etc. Two atoms created with different types can represent the same sequence of bytes. Atoms are first ordered on the rank number of the type and then on the result of the compare() function. Rank numbers are assigned when the type is registered. This implies that thre results of inequality comparisons between blobs of different types is undefined and can change if the program is run twice (the ordering within a blob type will not change, of course).

While the blob is alive, neither its handle nor the location of the contents (see PL_blob_data()) change. If the blob's type has the PL_BLOB_UNIQUE feature, the content of the blob must remain unmodified. Blobs are only reclaimed by the atom garbage collector. In this case the atom garbage collector calls the release(f)unction associated with the blob type and reclaims the memory allocated for the content unless this is owned by the creator of the blob indicated by the PL_BLOB_NOCOPY flag. After an atom_t value is reclaimed by the atom garbage collector, the value may be reused for allocating a new blob or atom.

If foreign code stores the atom_t handle in some permanent location it must make sure the handle is registered to prevent it from being garbage collected. If the handle is obtained from a term_t object it is not registered because it is protected by the term_t object. This applies to e.g., PL_get_atom(). Functions that create a handle from data such as PL_new_atom() return a registered handle to prevent the asynchronous atom garbage collector from reclaiming it immediately. Note that many of the API functions create an atom or blob handle and use this to fill a term_t object, e.g., PL_unify_blob(), PL_unify_chars(), etc. In this scenario the handle is protected by the term_t object. Registering and unregistering atom_t handles is done by PL_register_atom() and PL_unregister_atom().

Note that during program shutdown using PL_cleanup(), all atoms and blobs are reclaimed as described above. These objects are reclaimed regardless of their registration count. The order in which the atoms or blobs are reclaimed under PL_cleanup() is undefined. However, when these objects are reclaimed using garbage_collect_atoms/0, registration counts are taken into account.

12.4.8.1 Defining a BLOB type

The type PL_blob_t represents a structure with the layout displayed below. The structure contains additional fields at the ... for internal bookkeeping as well as future extensions.

typedef struct PL_blob_t
{ uintptr_t     magic;          /* PL_BLOB_MAGIC */
  uintptr_t     flags;          /* Bitwise or of PL_BLOB_* */
  const char *  name;           /* name of the type */
  int           (*release)(atom_t a);
  int           (*compare)(atom_t a, atom_t b);
  int           (*write)(IOSTREAM *s, atom_t a, int flags);
  void          (*acquire)(atom_t a);
  int           (*save)(atom_t a, IOSTREAM *s);
  atom_t        (*load)(IOSTREAM *s);
  ...
} PL_blob_t;

For each type, exactly one such structure should be allocated. Its first field must be initialised to PL_BLOB_MAGIC. The flags is a bitwise or of the following constants:

PL_BLOB_TEXT

If specified the blob is assumed to contain text and is considered a normal Prolog atom. The (currently) two predefined blob types that represent atoms have this flag set. User-defined blobs may not specify this, even if they contain only text. Applications should not use the blob API to create normal text atoms or get access to the text represented by normal text atoms. Most applications should use PL_get_nchars() and PL_unify_chars() to get text from Prolog terms or create Prolog terms that represent text.

PL_BLOB_UNIQUE

If specified the system ensures that the blob-handle is a unique reference for a blob with the given type, length and content. If this flag is not specified, each lookup creates a new blob. Uniqueness is determined by comparing the bytes in the blobs unless PL_BLOB_NOCOPY is also specified, in which case the pointers are compared.

PL_BLOB_NOCOPY

By default the content of the blob is copied. Using this flag the blob references the external data directly. The user must ensure the provided pointer is valid as long as the atom lives. If PL_BLOB_UNIQUE is also specified, uniqueness is determined by comparing the pointer rather than the data pointed at. Using PL_BLOB_UNIQUE|