From 4ab25d6d3f70c20ae5716b41550240ff7a165739 Mon Sep 17 00:00:00 2001
From: Gabriel Clima <gabriel.clima@gcore.com>
Date: Fri, 17 Apr 2026 07:55:30 +0000
Subject: [PATCH] Documented that directio does not apply to cached files.

Users commonly assume directio takes effect for files served from
proxy_cache (the most widespread nginx deployment), and configure it
expecting reduced page cache pressure on the cache path. It does not:
cached responses are served through buffered I/O regardless of the
directive. See https://github.com/nginx/nginx/pull/654 for context.
---
 xml/en/docs/http/ngx_http_core_module.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/xml/en/docs/http/ngx_http_core_module.xml b/xml/en/docs/http/ngx_http_core_module.xml
index a747b69ee..08c1415f7 100644
--- a/xml/en/docs/http/ngx_http_core_module.xml
+++ b/xml/en/docs/http/ngx_http_core_module.xml
@@ -522,7 +522,9 @@ the <c-def>O_DIRECT</c-def> flag (FreeBSD, Linux),
 the <c-def>F_NOCACHE</c-def> flag (macOS),
 or the <c-func>directio</c-func> function (Solaris),
 when reading files that are larger than or equal to
-the specified <value>size</value>.
+the specified <value>size</value>
+(does not apply to files served from the
+<link doc="ngx_http_proxy_module.xml" id="proxy_cache">proxy cache</link>).
 The directive automatically disables (0.7.15) the use of
 <link id="sendfile"/>
 for a given request.