Errors¶

Every failure is a ph_error_t; how to read one, and the details of the last failed load.

Types
`ph_error_t`	Result of every function that can fail: `PH_SUCCESS` (0) or a negative code.

Functions
`ph_get_error_string()`	Returns a human-readable string description for an error code.
`ph_get_last_error_message()`	Returns the detail of the last load on this context when it failed (the path and the operating system's reason, the decoder's complaint, the limit it hit), or an empty string if that load succeeded, no load has run, or the failure has no detail beyond its code.

Types¶

`ph_error_t`¶

Result of every function that can fail: PH_SUCCESS (0) or a negative code.

ph_get_error_string() names a code; ph_get_last_error_message() adds the details of the last failed load on a context.

ABI rule: every value here is spelled out explicitly, and new codes are only ever appended at the end of the list (before PH_ERR_FORCE_INT32_, which is not a code) with the next free negative value. Renumbering or reusing a value silently changes the meaning of an error in already-compiled consumers and in FFI bindings that hardcode the number, so a value, once assigned, is never handed to a different code.

Name	Value	Description
`PH_SUCCESS`	`0`	The call did what it was asked.
`PH_ERR_ALLOCATION_FAILED`	`-1`	A malloc() somewhere on the call path returned NULL – the input was fine, the process just could not get the memory it needed right now. This is transient and worth retrying, unlike PH_ERR_CORRUPT_DATA below, which is a verdict on the input itself. Reported identically by the native decoder backends (JPEG, PNG and WebP, on their own malloc() failing) and by the stb_image fallback (on stbi_load_from_memory() failing with its "outofmem" reason).
`PH_ERR_INVALID_ARGUMENT`	`-3`	A NULL pointer, or a value outside the documented range. Always a mistake in the call itself – a hash function called before any image was loaded is PH_ERR_EMPTY_IMAGE instead.
`PH_ERR_EMPTY_IMAGE`	`-5`	A hash was requested from a context that holds no image: nothing was loaded yet, or the last `ph_load_from_file()` / `ph_load_from_memory()` failed (a failed `ph_load_from_pixels()` keeps the previous image). Returned by every ph_compute_* function and `ph_compute_multi()`, after their pointer arguments have been checked.
`PH_ERR_IMAGE_TOO_LARGE`	`-6`	The image is larger than the context's max_pixels (see `ph_context_set_max_pixels()`) or than the fixed limits no setting lifts; or a buffer passed to a load is longer than the library can address. Decided before the pixels are allocated.
`PH_ERR_UNSUPPORTED_FORMAT`	`-7`	The data isn't any image format libphash recognizes.
`PH_ERR_CORRUPT_DATA`	`-8`	A recognized format's magic/header matched, but the bitstream itself is malformed or truncated.
`PH_ERR_DECODER_UNAVAILABLE`	`-9`	The format was recognized, but no decoder for it was compiled into this build (e.g. WebP without PH_USE_WEBP).
`PH_ERR_IO`	`-10`	The path could not be used as an image source at all: it does not exist (including a dangling symlink), could not be opened (permissions), is not a regular file (a directory, a device, a FIFO), or is an empty file. It is decided before any decoder sees the bytes, and is reported identically on POSIX and Windows.
`PH_ERR_REQUIRES_COLOR`	`-11`	A color algorithm (`ph_compute_color_hash()`, `ph_compute_color_moments_hash()`) was asked to run on an image that carries fewer than 3 channels – see `ph_context_set_load_grayscale()`.
`PH_ERR_CANCELLED`	`-12`	A batch was stopped by its should_continue callback (see `ph_batch_options_t`) before this item was started. Returned by `ph_hash_files_ex()` / `ph_hash_buffers_ex()` and stored in the `status` of every item they never reached.
`PH_ERR_NO_STRUCTURE`	`-13`	`ph_radial_similarity()` was given a digest with no structure to compare: the all-zero digest `ph_compute_radial_hash()` returns for an image with no angular structure (flat, or radially symmetric).
`PH_ERR_FORCE_INT32_`	`PH_ENUM_FORCE_INT32_VALUE`	Not an error code – see "Enum width".

Returned by — read from each function's Returns. Every function that returns ph_error_t returns PH_SUCCESS when it succeeds.

Code	Returned by
`PH_ERR_ALLOCATION_FAILED`	`ph_create()` · `ph_load_from_file()` · `ph_load_from_memory()` · `ph_load_from_pixels()` · `ph_compute_ahash()` · `ph_compute_dhash()` · `ph_compute_phash()` · `ph_compute_whash()` · `ph_compute_multi()` · `ph_hash_files()` · `ph_hash_buffers()` · `ph_hash_files_ex()` · `ph_hash_buffers_ex()` · `ph_compute_digest()` · `ph_compute_bmh()` · `ph_compute_mhash()` · `ph_compute_radial_hash()`
`PH_ERR_INVALID_ARGUMENT`	All 42 functions that return `ph_error_t`
`PH_ERR_EMPTY_IMAGE`	`ph_compute_ahash()` · `ph_compute_dhash()` · `ph_compute_phash()` · `ph_compute_whash()` · `ph_compute_multi()` · `ph_compute_digest()` · `ph_compute_bmh()` · `ph_compute_color_moments_hash()` · `ph_compute_color_hash()` · `ph_compute_mhash()` · `ph_compute_radial_hash()`
`PH_ERR_IMAGE_TOO_LARGE`	`ph_load_from_file()` · `ph_load_from_memory()` · `ph_load_from_pixels()`
`PH_ERR_UNSUPPORTED_FORMAT`	`ph_load_from_file()` · `ph_load_from_memory()`
`PH_ERR_CORRUPT_DATA`	`ph_load_from_file()` · `ph_load_from_memory()`
`PH_ERR_DECODER_UNAVAILABLE`	`ph_load_from_file()` · `ph_load_from_memory()`
`PH_ERR_IO`	`ph_load_from_file()`
`PH_ERR_REQUIRES_COLOR`	`ph_compute_digest()` · `ph_compute_color_moments_hash()` · `ph_compute_color_hash()`
`PH_ERR_CANCELLED`	`ph_hash_files_ex()` · `ph_hash_buffers_ex()`
`PH_ERR_NO_STRUCTURE`	`ph_radial_similarity()`

Functions¶

`ph_get_error_string()`¶

const char *ph_get_error_string(ph_error_t err);

returns const char *

Returns a human-readable string description for an error code.

Parameters

Parameter	Description
`err`	The error code.

Returns A constant string describing the error. Never returns NULL.

`ph_get_last_error_message()`¶

const char *ph_get_last_error_message(const ph_context_t *ctx);

returns const char *

Returns the detail of the last load on this context when it failed (the path and the operating system's reason, the decoder's complaint, the limit it hit), or an empty string if that load succeeded, no load has run, or the failure has no detail beyond its code.

Every ph_load_from_*() call clears it on the way in; hashes, setters and comparisons neither set nor clear it. The text is English, for a log or a person: a program branches on the ph_error_t code. A file's message quotes the whole path, up to the longest the system opens, and then the reason; a longer path keeps its two ends around "...", and the reason is never cut. See Handling errors.

Note

Not thread-safe to read concurrently with a load call on the same context; follows the same "one context per thread at a time" rule as the rest of the API. The returned pointer is owned by the context and is invalidated by the next load/free call on it.

Parameters

Parameter	Description
`ctx`	The context. Passing NULL returns an empty string.

Errors¶

Types¶

ph_error_t¶

Functions¶

ph_get_error_string()¶

ph_get_last_error_message()¶

`ph_error_t`¶

`ph_get_error_string()`¶

`ph_get_last_error_message()`¶