SWI-Prolog -- API-function PL_unify

Documentation
- Reference manual
  - Foreign Language Interface
    - The Foreign Include File
      - BLOBS: Using atoms to store arbitrary binary data
        
        Accessing blobs
        
        PL_is_blob()
        
        PL_unify_blob()
        
        PL_put_blob()
        
        PL_new_blob()
        
        PL_get_blob()
        
        PL_blob_data()
        
        PL_free_blob()
- Packages

Availability:C-language interface function

bool PL_unify_blob(term_t t, void *blob, size_t len, PL_blob_t *type)

Unify t to a blob constructed from the given data and associated with the given type. This performs the following steps:

If the type has PL_BLOB_UNIQUE set, search the blob database for a blob of the same type with the same content. If found, unify t with the existing handle.
If not found or PL_BLOB_UNIQUE is not set, create a new blob handle. If PL_BLOB_NOCOPY is set, associate it to the given memory; else, copy the memory to a new area owned by the blob. Call the acquire() function of the type.
Unify t with the existing or new handle. This succeeds if t is already bound to the existing blob handle. If t is a variable, it succeeds if sufficient resources are available to perform the unification; if t is bound to something else, this fails.

It is possible that a blob referencing critial resources is created after which the unification fails. Typically these resources are eventually reclaimed because the new blob is not referenced and reclaimed by the atom garbage collector. As described with the release() function, it can be desirable to reclaim the critical resources after the failing PL_unify_blob() call.