Some documentation for local gcc changes.

Insights and grumblings from Theo, Todd, Miod.

3 files changed, 115 insertions, 4 deletions

diff --git a/gnu/egcs/gcc/Makefile.bsd-wrapper b/gnu/egcs/gcc/Makefile.bsd-wrapper
index 047763e261d..bcc9bd80296 100644
--- a/gnu/egcs/gcc/Makefile.bsd-wrapper
+++ b/gnu/egcs/gcc/Makefile.bsd-wrapper
@@ -1,6 +1,6 @@
-#	$OpenBSD: Makefile.bsd-wrapper,v 1.9 2002/11/22 20:26:12 marc Exp $
+#	$OpenBSD: Makefile.bsd-wrapper,v 1.10 2002/11/24 00:58:16 espie Exp $
 
-MAN=		cccp.1 gcc.1 
+MAN=		cccp.1 gcc.1 gcc-local.1
 MLINKS+=	gcc.1 cc.1
 MLINKS+=	cccp.1 cpp.1
 
diff --git a/gnu/egcs/gcc/gcc-local.1 b/gnu/egcs/gcc/gcc-local.1
new file mode 100644
index 00000000000..f98e3380cf9
--- /dev/null
+++ b/gnu/egcs/gcc/gcc-local.1
@@ -0,0 +1,108 @@
+.\" $OpenBSD: gcc-local.1,v 1.1 2002/11/24 00:58:17 espie Exp $
+.\"
+.\" Copyright (c) 2002 Marc Espie
+.\"
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd Nov. 23, 2002
+.Dt GCC-LOCAL 1
+.Os
+.Sh NAME
+.Nm gcc-local
+.Nd local modifications to gcc
+.Sh DESCRIPTION
+The
+.Nm gcc
+software comes with specific modifications for
+.Ox .
+.Bl -dash
+.It
+.Nm gcc
+does not search under 
+.Pa /usr/local
+for include files nor for libraries:
+as a system compiler, it only searches the system paths by default.
+.It
+On
+.Ox ,
+the 
+.Fl pthread
+option should be used to link threaded code, isolating the program from
+operating system details.
+.It
+On most architectures,
+trampoline code marks the smallest possible area around the trampoline stub 
+executable using 
+.Xr mprotect 2 ,
+since the stack area is by default non-executable.
+.It
+The 
+.Fl O2
+option does not include 
+.Fl fstrict-aliasing ,
+as this option causes issues on some legacy code.
+.Fl fstrict-aliasing
+is very unsafe with code that plays tricks with casts, bypassing the 
+already weak type system of C.
+.It
+.Nm gcc
+recognizes the extra format attribute syslog, to better match
+the definition of 
+.Xr syslog 2 ,
+and shut erroneous warnings when used with
+.Fl pedantic .
+.It
+.Nm gcc
+recognizes the extra attribute nonnull, which can be used to mark
+arguments that can't be 
+.Dv NULL .
+On the other hand, the printf format attribute does not imply nonnull
+for the format.
+This allows for correct format checking on the
+.Xr err 3
+function family.
+.It
+.Nm gcc
+recognizes the extra attribute sentinel, which can be used to mark varargs
+function that need a
+.Dv NULL
+pointer to mark argument termination, like
+.Xr execl 3 .
+This exposes latent bugs for 64 bit architectures,
+where a terminating 0 will expand to a 32 bit int, and not a full-fledged
+64 bits pointer.
+.It
+On some
+.Ox
+platforms, 
+.Nm gcc
+still uses 
+.Xr setjmp 3 /
+.Xr longjump 3 -
+style exceptions, and so needs extra fixes beyond the pure 2.95.3 release.
+.It
+On i386, the optimizer features an extra peephole which reduces the function
+prologues enough to allow for the ramdisk to fit on one floppy.
+.El
+.Sh SEE ALSO
+.Xr gcc 1 
diff --git a/gnu/egcs/gcc/gcc.1 b/gnu/egcs/gcc/gcc.1
index a3b197b7029..ae5ccdb82f5 100644
--- a/gnu/egcs/gcc/gcc.1
+++ b/gnu/egcs/gcc/gcc.1
@@ -20,10 +20,10 @@
 .if n .sp
 .if t .sp 0.4
 ..
-.Id $Id: gcc.1,v 1.1 1999/05/26 13:34:17 espie Exp $
+.Id $Id: gcc.1,v 1.2 2002/11/24 00:58:17 espie Exp $
 .TH GCC 1 "\*(Dt" "GNU Tools" "GNU Tools"
 .SH NAME
-gcc, g++ \- GNU project C and C++ Compiler (egcs-1.1)
+gcc, g++ \- GNU project C and C++ Compiler (gcc-2.95)
 .SH SYNOPSIS
 .B gcc
 .RI "[ " option " | " filename " ].\|.\|."
@@ -31,6 +31,9 @@ gcc, g++ \- GNU project C and C++ Compiler (egcs-1.1)
 .B g++
 .RI "[ " option " | " filename " ].\|.\|."
 .SH WARNING
+The compiler bundled with OpenBSD differs significantly from the actual
+2.95.3 release of the FSF. See gcc-local(1) for details.
+.SH WARNING
 The information in this man page is an extract from the full
 documentation of the GNU C compiler, and is limited to the meaning of
 the options.