Version and build¶

The library's version, the decoders it was built with, and the ABI conventions.

Constants¶

PH_ENUM_FORCE_INT32_VALUE¶

#define PH_ENUM_FORCE_INT32_VALUE 0x7FFFFFFF

The value of every public enum's *_FORCE_INT32_ enumerator.

Every public enum ends in a *_FORCE_INT32_ enumerator. It is not a value any function accepts or returns: it exists only to make the enum's range need a full 32-bit int, so that the enum is 4 bytes wide under every compiler and flag. Without it, -fshort-enums – the default ABI on ARM EABI targets – shrinks an enum to the smallest type that holds its values, and a library and a consumer built with different settings disagree on the width of every ph_error_t return value and of the status field in the batch structs. Nothing diagnoses that mismatch; the caller just reads garbage. The width of a public enum is part of the ABI.

Functions¶

ph_version()¶

const char *ph_version(void);

returns const char *

Returns the library version string (e.g., "2.0.0").

Used in cmake_consumer/main.c

ph_version_number()¶

int ph_version_number(void);

returns int

Returns the library version as a single comparable integer: the same value as the PH_VERSION_NUMBER macro the library was compiled with (major*1000000 + minor*1000 + patch, e.g. 2.0.0 -> 2000000). That macro comes with this header (from phash_version.h, which it includes); comparing the two tells a caller whether the header it compiled against and the library it runs with are the same version. Intended for FFI callers doing compatibility checks without string parsing.

Used in find_duplicates.c

Explained in Storing and searching hashes

ph_can_use_jpeg()¶

int ph_can_use_jpeg(void);

returns int

Whether this build has a native JPEG decoder (libjpeg-turbo), decided when the library was compiled.

Returns 1 if it does, 0 if JPEG goes through the bundled stb_image fallback.

Used in find_duplicates.c

Explained in How libphash works · Installing · Loading images · Storing and searching hashes

ph_can_use_png()¶

int ph_can_use_png(void);

returns int

Whether this build has a native PNG decoder, decided when the library was compiled.

Native means libpng.

Returns 1 if PNG is decoded natively, 0 if it goes through the stb_image fallback.

Explained in How libphash works · Installing · Loading images

ph_can_use_webp()¶

int ph_can_use_webp(void);

returns int

Whether this build decodes WebP with libwebp, decided when the library was compiled.

Returns 1 if it does, 0 if WebP is not supported at all (loading one returns PH_ERR_DECODER_UNAVAILABLE; stb_image has no WebP decoder).

Explained in Handling errors · How libphash works · Installing · Loading images

ph_get_build_info()¶

const char *ph_get_build_info(void);

returns const char *

Describes how this library binary was built, as one line of text for logs and bug reports.

Space-separated key=value pairs, for example: version=2.0.0 jpeg=libjpeg-turbo png=libpng webp=libwebp zlib=zlib-ng threads=on simd=neon mock=off

• jpeg: libjpeg-turbo or stb. A JPEG can hash a few bits apart under the two (Comparing hashes); no other build difference changes a hash;
• png: libpng or stb; webp: libwebp or none; zlib: zlib-ng, zlib or none (stb_image inflates PNG itself);
• threads: on if the batch functions can use worker threads, off if they always run sequentially;
• simd: the widest instruction set the library was compiled for – avx2, sse4.2, neon or none;
• mock: on only in a test build that registers the mock decoder (PHASH_ENABLE_MOCK_BACKEND); a shipped library says off.

Keys keep their meaning; later versions may add keys at the end and add values to a key's list. Meant to be logged, not parsed for decisions – to branch on a decoder, use ph_can_use_jpeg(), ph_can_use_png() and ph_can_use_webp().

Returns A static NUL-terminated string. Never NULL; the caller must not free it.

Used in cmake_consumer/main.c

Explained in Hashing many files · How libphash works · Installing · Loading images · Comparing hashes · Image preparation