crate: annotate unstable *MAX constants

There were troublesome symbols. Upstrem releases can change them. The
frequency of change is inconvenient. This makes SemVer inconvenient.

Users may need advice. This patch does that.

Author: dybucc

src/fuchsia/mod.rs

@@ -1592,6 +1592,8 @@ pub const LOCK_UN: c_int = 8;
 pub const SS_ONSTACK: c_int = 1;
 pub const SS_DISABLE: c_int = 2;
 
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const PATH_MAX: c_int = 4096;
 
 pub const FD_SETSIZE: c_int = 1024;

src/new/linux_uapi/linux/can/j1939.rs

@@ -57,4 +57,6 @@ s! {
     }
 }
 
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const J1939_FILTER_MAX: c_int = 512;

src/new/linux_uapi/linux/can/raw.rs

@@ -3,6 +3,9 @@
 pub use crate::linux::can::*;
 
 pub const SOL_CAN_RAW: c_int = SOL_CAN_BASE + CAN_RAW;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const CAN_RAW_FILTER_MAX: c_int = 512;
 
 // FIXME(cleanup): use `c_enum!`, which needs to be adapted to allow omitting a type.

src/new/qurt/limits.rs

@@ -27,12 +27,22 @@ pub const USHRT_MAX: c_ushort = 65535;
 // POSIX Limits
 pub const ARG_MAX: c_int = 4096;
 pub const CHILD_MAX: c_int = 25;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const LINK_MAX: c_int = 8;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const NAME_MAX: c_int = 255;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const PATH_MAX: c_int = 260;
+
 pub const MAX_CANON: c_int = 255;
 pub const MAX_INPUT: c_int = 255;
-pub const NAME_MAX: c_int = 255;
 pub const OPEN_MAX: c_int = 20;
-pub const PATH_MAX: c_int = 260;
 pub const PIPE_BUF: c_int = 512;
 pub const STREAM_MAX: c_int = 20;
 pub const TZNAME_MAX: c_int = 50;

src/new/qurt/signal.rs

@@ -51,6 +51,9 @@ pub const SIG_SETMASK: c_int = 3;
 pub const POSIX_MSG: c_int = 7;
 pub const POSIX_NOTIF: c_int = 8;
 pub const SIGRTMIN: c_int = 10;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const SIGRTMAX: c_int = 32;
 
 // Notification types (from QuRT signal.h)

src/unix/aix/mod.rs

@@ -932,7 +932,11 @@ pub const RTAX_IFP: c_int = 4;
 pub const RTAX_IFA: c_int = 5;
 pub const RTAX_AUTHOR: c_int = 6;
 pub const RTAX_BRD: c_int = 7;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const RTAX_MAX: c_int = 8;
+
 pub const RTF_UP: c_int = 0x1;
 pub const RTF_GATEWAY: c_int = 0x2;
 pub const RTF_HOST: c_int = 0x4;
@@ -1445,7 +1449,39 @@ pub const L_GETPROCINFO: c_int = 7;
 pub const L_GETXINFO: c_int = 8;
 
 // sys/limits.h
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const PATH_MAX: c_int = 1023;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const BC_BASE_MAX: c_int = 99;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const BC_DIM_MAX: c_int = 0x800;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const BC_SCALE_MAX: c_int = 99;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const BC_STRING_MAX: c_int = 0x800;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const CHARCLASS_NAME_MAX: c_int = 14;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const COLL_WEIGHTS_MAX: c_int = 4;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
+pub const EXPR_NEST_MAX: c_int = 32;
+
 pub const PAGESIZE: c_int = 4096;
 pub const IOV_MAX: c_int = 16;
 pub const AIO_LISTIO_MAX: c_int = 4096;
@@ -1454,14 +1490,7 @@ pub const OPEN_MAX: c_int = 65534;
 pub const MAX_INPUT: c_int = 512;
 pub const MAX_CANON: c_int = 256;
 pub const ARG_MAX: c_int = 1048576;
-pub const BC_BASE_MAX: c_int = 99;
-pub const BC_DIM_MAX: c_int = 0x800;
-pub const BC_SCALE_MAX: c_int = 99;
-pub const BC_STRING_MAX: c_int = 0x800;
-pub const CHARCLASS_NAME_MAX: c_int = 14;
 pub const CHILD_MAX: c_int = 128;
-pub const COLL_WEIGHTS_MAX: c_int = 4;
-pub const EXPR_NEST_MAX: c_int = 32;
 pub const NZERO: c_int = 20;
 
 // sys/lockf.h
@@ -1541,7 +1570,11 @@ pub const MAXPATHLEN: c_int = PATH_MAX + 1;
 pub const MAXSYMLINKS: c_int = 20;
 pub const MAXHOSTNAMELEN: c_int = 256;
 pub const MAXUPRC: c_int = 128;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const NGROUPS_MAX: c_ulong = 2048;
+
 pub const NGROUPS: c_ulong = NGROUPS_MAX;
 pub const NOFILE: c_int = OPEN_MAX;
 
@@ -1739,7 +1772,11 @@ pub const SIGXCPU: c_int = 24;
 pub const SIGXFSZ: c_int = 25;
 pub const SIGTRAP: c_int = 5;
 pub const SIGCLD: c_int = 20;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const SIGRTMAX: c_int = 57;
+
 pub const SIGRTMIN: c_int = 50;
 pub const SI_USER: c_int = 0;
 pub const SI_UNDEFINED: c_int = 8;
@@ -1817,7 +1854,11 @@ pub const AF_INET6: c_int = 24;
 pub const AF_INTF: c_int = 20;
 pub const AF_RIF: c_int = 21;
 pub const AF_NDD: c_int = 23;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const AF_MAX: c_int = 30;
+
 pub const PF_UNSPEC: c_int = AF_UNSPEC;
 pub const PF_UNIX: c_int = AF_UNIX;
 pub const PF_INET: c_int = AF_INET;
@@ -1843,7 +1884,11 @@ pub const PF_RIF: c_int = AF_RIF;
 pub const PF_INTF: c_int = AF_INTF;
 pub const PF_NDD: c_int = AF_NDD;
 pub const PF_INET6: c_int = AF_INET6;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const PF_MAX: c_int = AF_MAX;
+
 pub const SF_CLOSE: c_int = 1;
 pub const SF_REUSE: c_int = 2;
 pub const SF_DONT_CACHE: c_int = 4;

src/unix/bsd/apple/mod.rs

@@ -2014,6 +2014,9 @@ pub const CPU_STATE_USER: c_int = 0;
 pub const CPU_STATE_SYSTEM: c_int = 1;
 pub const CPU_STATE_IDLE: c_int = 2;
 pub const CPU_STATE_NICE: c_int = 3;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const CPU_STATE_MAX: c_int = 4;
 
 pub const PROCESSOR_BASIC_INFO: c_int = 1;
@@ -3399,14 +3402,39 @@ pub const HW_TARGET: c_int = 26;
 pub const HW_PRODUCT: c_int = 27;
 pub const HW_MAXID: c_int = 28;
 pub const USER_CS_PATH: c_int = 1;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_BASE_MAX: c_int = 2;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_DIM_MAX: c_int = 3;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_SCALE_MAX: c_int = 4;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_STRING_MAX: c_int = 5;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_COLL_WEIGHTS_MAX: c_int = 6;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_EXPR_NEST_MAX: c_int = 7;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_LINE_MAX: c_int = 8;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_RE_DUP_MAX: c_int = 9;
+
 pub const USER_POSIX2_VERSION: c_int = 10;
 pub const USER_POSIX2_C_BIND: c_int = 11;
 pub const USER_POSIX2_C_DEV: c_int = 12;
@@ -3450,10 +3478,6 @@ pub const SIGEV_THREAD: c_int = 3;
 pub const AIO_CANCELED: c_int = 2;
 pub const AIO_NOTCANCELED: c_int = 4;
 pub const AIO_ALLDONE: c_int = 1;
-#[deprecated(
-    since = "0.2.64",
-    note = "Can vary at runtime.  Use sysconf(3) instead"
-)]
 pub const AIO_LISTIO_MAX: c_int = 16;
 pub const LIO_NOP: c_int = 0;
 pub const LIO_WRITE: c_int = 2;
@@ -3529,6 +3553,8 @@ pub const RTV_SSTHRESH: c_int = 0x20;
 pub const RTV_RTT: c_int = 0x40;
 pub const RTV_RTTVAR: c_int = 0x80;
 
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const RTAX_MAX: c_int = 8;
 
 pub const KERN_PROCARGS2: c_int = 49;

src/unix/bsd/freebsdlike/dragonfly/mod.rs

@@ -645,14 +645,39 @@ pub const HW_MACHINE_PLATFORM: c_int = 12;
 pub const HW_SENSORS: c_int = 13;
 pub const HW_MAXID: c_int = 14;
 pub const USER_CS_PATH: c_int = 1;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_BASE_MAX: c_int = 2;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_DIM_MAX: c_int = 3;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_SCALE_MAX: c_int = 4;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_BC_STRING_MAX: c_int = 5;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_COLL_WEIGHTS_MAX: c_int = 6;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_EXPR_NEST_MAX: c_int = 7;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_LINE_MAX: c_int = 8;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const USER_RE_DUP_MAX: c_int = 9;
+
 pub const USER_POSIX2_VERSION: c_int = 10;
 pub const USER_POSIX2_C_BIND: c_int = 11;
 pub const USER_POSIX2_C_DEV: c_int = 12;
@@ -1172,6 +1197,9 @@ pub const RTM_VERSION: c_int = 7;
 pub const RTAX_MPLS1: c_int = 8;
 pub const RTAX_MPLS2: c_int = 9;
 pub const RTAX_MPLS3: c_int = 10;
+
+/// This symbol is prone to change across releases upstream.
+/// See the [usage guidelines](crate::#usage-guidelines) for details and use.
 pub const RTAX_MAX: c_int = 11;
 
 const fn _CMSG_ALIGN(n: usize) -> usize {