doc/libvips-header.md
Title: Operator index > By section > Header
<!-- libvips/iofuncs/header.c -->libvips supports getting and setting image header data (including metadata) in a uniform way.
Use [[email protected]_typeof] to test for the existence and [[email protected]] of a header field.
You can attach arbitrary metadata to images. Metadata is copied as images are processed, so all images which used this image as input, directly or indirectly, will have this same bit of metadata attached to them. Copying is implemented with reference-counted pointers, so it is efficient, even for large items of data. This does however mean that metadata items need to be immutable. Metadata is handy for things like ICC profiles or EXIF data.
Various convenience functions (e.g. [[email protected]_int]) let you easily attach simple types like numbers, strings and memory blocks to images. Use [[email protected]] to loop over an image's fields, including all metadata.
Items of metadata are identified by strings. Some strings are reserved, for example the ICC profile for an image is known by convention as "icc-profile-data" (i.e. the [const@META_ICC_NAME] constant).
If you save an image in .v format, all metadata (with a restriction, see
below) is automatically saved for you in a block of XML at the end of the
file. When you load a .v image, the metadata is restored. You can use the
vipsedit command-line tool to extract or replace this block of XML.
.v metadata is based on [[email protected]]. See the docs for that
system if you want to do fancy stuff such as defining a new metadata type.
libvips defines a new [[email protected]] called [struct@SaveString], a
variety of string, see [func@value_set_save_string]. If your
[[email protected]] can be transformed to [struct@SaveString], it will
be saved and loaded to and from .v files for you.
libvips provides a couple of base classes which implement reference-counted areas of memory. If you base your metadata on one of these types, it can be copied between images efficiently.