IWYU widely useful pragmas

Add various widely useful "IWYU pragma" annotations, such as

- Common header files such as c.h, postgres.h should be "always_keep".

- System headers included in c.h, postgres.h etc. should be considered
  "export".

- Some portability headers such as getopt_long.h should be
  "always_keep", so they are not considered superfluous on some
  platforms.

- Certain system headers included from portability headers should be
  considered "export" because the purpose of the portability header is
  to wrap them.

- Superfluous includes marked as "for backward compatibility" get a
  formal IWYU annotation.

- Generated header included in utils/syscache.h is marked exported.
  This is a very commonly used include and this avoids lots of
  complaints.

Discussion: https://www.postgresql.org/message-id/flat/9395d484-eff4-47c2-b276-8e228526c8ae@eisentraut.org

src/include/c.h

@@ -16,6 +16,7 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 /*
  *----------------------------------------------------------------
  *	 TABLE OF CONTENTS
@@ -46,6 +47,8 @@
 #ifndef C_H
 #define C_H
 
+/* IWYU pragma: begin_exports */
+
 /*
  * These headers must be included before any system headers, because on some
  * platforms they affect the behavior of the system headers (for example, by
@@ -1327,4 +1330,6 @@ typedef intptr_t sigjmp_buf[5];
 /* /port compatibility functions */
 #include "port.h"
 
+/* IWYU pragma: end_exports */
+
 #endif							/* C_H */

src/include/getopt_long.h

@@ -6,10 +6,11 @@
  *
  * src/include/getopt_long.h
  */
+/* IWYU pragma: always_keep */
 #ifndef GETOPT_LONG_H
 #define GETOPT_LONG_H
 
-#include "pg_getopt.h"
+#include "pg_getopt.h"			/* IWYU pragma: export */
 
 #ifndef HAVE_STRUCT_OPTION
 

src/include/pg_getopt.h

@@ -15,15 +15,16 @@
  *
  * src/include/pg_getopt.h
  */
+/* IWYU pragma: always_keep */
 #ifndef PG_GETOPT_H
 #define PG_GETOPT_H
 
 /* POSIX says getopt() is provided by unistd.h */
-#include <unistd.h>
+#include <unistd.h>				/* IWYU pragma: export */
 
 /* rely on the system's getopt.h if present */
 #ifdef HAVE_GETOPT_H
-#include <getopt.h>
+#include <getopt.h>				/* IWYU pragma: export */
 #endif
 
 /*

src/include/pg_trace.h

@@ -12,6 +12,6 @@
 #ifndef PG_TRACE_H
 #define PG_TRACE_H
 
-#include "utils/probes.h"
+#include "utils/probes.h"		/* IWYU pragma: export */
 
 #endif							/* PG_TRACE_H */

src/include/pgstat.h

@@ -16,11 +16,11 @@
 #include "portability/instr_time.h"
 #include "postmaster/pgarch.h"	/* for MAX_XFN_CHARS */
 #include "replication/conflict.h"
-#include "utils/backend_progress.h" /* for backward compatibility */
-#include "utils/backend_status.h"	/* for backward compatibility */
+#include "utils/backend_progress.h" /* for backward compatibility */	/* IWYU pragma: export */
+#include "utils/backend_status.h"	/* for backward compatibility */	/* IWYU pragma: export */
 #include "utils/pgstat_kind.h"
 #include "utils/relcache.h"
-#include "utils/wait_event.h"	/* for backward compatibility */
+#include "utils/wait_event.h"	/* for backward compatibility */	/* IWYU pragma: export */
 
 
 /* ----------

src/include/port/pg_iovec.h

@@ -16,7 +16,7 @@
 #ifndef WIN32
 
 #include <limits.h>
-#include <sys/uio.h>
+#include <sys/uio.h>			/* IWYU pragma: export */
 #include <unistd.h>
 
 #else

src/include/port/pg_pthread.h

@@ -13,7 +13,7 @@
 #ifndef PG_PTHREAD_H
 #define PG_PTHREAD_H
 
-#include <pthread.h>
+#include <pthread.h>			/* IWYU pragma: export */
 
 #ifndef HAVE_PTHREAD_BARRIER_WAIT
 

src/include/postgres.h

@@ -14,6 +14,7 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 /*
  *----------------------------------------------------------------
  *	 TABLE OF CONTENTS
@@ -42,10 +43,14 @@
 #ifndef POSTGRES_H
 #define POSTGRES_H
 
+/* IWYU pragma: begin_exports */
+
 #include "c.h"
 #include "utils/elog.h"
 #include "utils/palloc.h"
 
+/* IWYU pragma: end_exports */
+
 /* ----------------------------------------------------------------
  *				Section 1:	Datum type + support functions
  * ----------------------------------------------------------------

src/include/postgres_ext.h

@@ -19,6 +19,7 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 
 #ifndef POSTGRES_EXT_H
 #define POSTGRES_EXT_H

src/include/postgres_fe.h

@@ -15,6 +15,7 @@
  *
  *-------------------------------------------------------------------------
  */
+/* IWYU pragma: always_keep */
 #ifndef POSTGRES_FE_H
 #define POSTGRES_FE_H
 
@@ -22,8 +23,12 @@
 #define FRONTEND 1
 #endif
 
+/* IWYU pragma: begin_exports */
+
 #include "c.h"
 
 #include "common/fe_memutils.h"
 
+/* IWYU pragma: end_exports */
+
 #endif							/* POSTGRES_FE_H */

src/include/utils/syscache.h

@@ -20,7 +20,7 @@
 #include "access/htup.h"
 /* we intentionally do not include utils/catcache.h here */
 
-#include "catalog/syscache_ids.h"
+#include "catalog/syscache_ids.h"	/* IWYU pragma: export */
 
 extern void InitCatalogCache(void);
 extern void InitCatalogCachePhase2(void);

src/interfaces/libpq/libpq-int.h

@@ -44,6 +44,7 @@
 #include "fe-auth-sasl.h"
 #include "pqexpbuffer.h"
 
+/* IWYU pragma: begin_exports */
 #ifdef ENABLE_GSS
 #if defined(HAVE_GSSAPI_H)
 #include <gssapi.h>
@@ -51,6 +52,7 @@
 #include <gssapi/gssapi.h>
 #endif
 #endif
+/* IWYU pragma: end_exports */
 
 #ifdef ENABLE_SSPI
 #define SECURITY_WIN32