[glib] docs: Discourage use of gstdio.h and clarify its header requirements

[Philip Withnall <pwithnall src gnome org>]

commit 1a5cebec3996a27ab0e685679687d6b38120bf5f
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Sep 12 12:20:18 2017 +0100

    docs: Discourage use of gstdio.h and clarify its header requirements
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://bugzilla.gnome.org/show_bug.cgi?id=781598

 docs/reference/glib/glib-sections.txt |    2 +-
 glib/gfileutils.c                     |    9 +++++++++
 2 files changed, 10 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index e8a7fc8..7f7668c 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 e52f284..e995c4a 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`