= nng_http_server_set_error_file(3http)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_http_server_set_error_file - set custom HTTP error file

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>
#include <nng/supplemental/http/http.h>

int nng_http_server_set_error_file(nng_http_server *server,
        uint16_t code, const char *path);
----

== DESCRIPTION

The `nng_http_server_set_error_file()` sets an error page to be used
for HTTP status _code_ on the server instance _server_.
The body content of the HTTP responses will contain the file contents of
the file located at _path_, which should be an HTML file.

The custom HTML content will be used when the server is returning an
internally generated error response, or is returning an error response
that was allocated with the
xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`]
function.
This HTML content will also be used if the application calls the
xref:nng_http_server_res_error.3http.adoc[`nng_http_server_res_error()`].
The last custom error page set for _code_ by either this function or
xref:`nng_http_server_set_error_page.3http.adoc[`nng_http_server_error_page()`]
will be used.

NOTE: Error responses that have their body content changed after allocation,
or that are written directly by the application, will not use the body
content supplied here.

NOTE: The file contents of _path_ are read when this function is called.
Therefore, if the file contents are changed, then this function should
be called again to update the error page.

== RETURN VALUES

This function returns 0 on success, and non-zero otherwise.

== ERRORS

[horizontal]
`NNG_ENOENT`:: The file named by _path_ does not exist.
`NNG_EPERM`:: No permission to read the file named by _path_.
`NNG_ENOMEM`:: Insufficient free memory exists.
`NNG_ENOTSUP`:: HTTP not supported.

== SEE ALSO

[.text-left]
xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)],
xref:nng_http_server_hold.3http.adoc[nng_http_server_hold(3http)],
xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error(3http)],
xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page(3http)],
xref:nng_strerror.3.adoc[nng_strerror(3)],
xref:nng.7.adoc[nng(7)]