diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index e8a7fc868..7f7668c4a 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1324,7 +1324,7 @@ g_option_error_quark
 <SECTION>
 <TITLE>File Utilities</TITLE>
 <FILE>fileutils</FILE>
-<INCLUDE>glib.h,glib/gstdio.h</INCLUDE>
+<INCLUDE>glib.h,glib/gstdio.h,fcntl.h,sys/types.h,sys/stat.h</INCLUDE>
 GFileError
 G_FILE_ERROR
 GFileTest
diff --git a/glib/gfileutils.c b/glib/gfileutils.c
index e52f284eb..e995c4a2b 100644
--- a/glib/gfileutils.c
+++ b/glib/gfileutils.c
@@ -62,6 +62,10 @@
  * @title: File Utilities
  * @short_description: various file-related functions
  *
+ * Do not use these APIs unless you are porting a POSIX application to Windows.
+ * A more high-level file access API is provided as GIO — see the documentation
+ * for #GFile.
+ *
  * There is a group of functions which wrap the common POSIX functions
  * dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
  * g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
@@ -69,6 +73,11 @@
  * characters in them on Windows without having to use ifdefs and the
  * wide character API in the application code.
  *
+ * On some Unix systems, these APIs may be defined as identical to their POSIX
+ * counterparts. For this reason, you must check for and include the necessary
+ * header files (such as `fcntl.h`) before using functions like g_creat(). You
+ * must also define the relevant feature test macros.
+ *
  * The pathname argument should be in the GLib file name encoding.
  * On POSIX this is the actual on-disk encoding which might correspond
  * to the locale settings of the process (or the `G_FILENAME_ENCODING`