gno/NOTES/notes.960227

7 Jan 97

$Id: notes.960227,v 1.2 1997/03/05 07:25:48 gdr Exp $

Header File Changes
===================

Where the Orca headers no longer suffice, effort has been made to make use
of the BSD 4.4 headers with minimal modifications.

Some BSD headers, due to the filenames used, cannot be placed on ProDOS
filesystems.  There are a few problems with this (in my perceived order
of priority):
	- having headers on HFS volumes slows down compilations
	- the usual lack of disk optimization/fixing avail for HFS
	- there are GNO users that don't use HFS volumes
OTOH, we don't want in general to break ported code which uses source like
	#include <net/if_arp.h>
Therefore, I have renamed the original source files to use ProDOS naming
conventions.  In this example, the new file is <net/if.arp.h>.  There
is *also* a file called <net/if_arp.h> which can be installed on an
HFS volume, but this contains little more than an #include <net/if.arp.h>.
This way, the headers which require an HFS volume can be _optionally_
installed by the GNO user.

For the sake of compile time efficiency, I've been changing lines in
the GNO system header files like
	#include <sys/types.h>
to
	#ifndef _SYS_TYPES_H_
	#include <sys/types.h>
	#endif
This isn't complete, but it's getting there.  I didn't touch any Orca/C
headers that used nested #includes but otherwise needed no modifications.

13/orcacdefs/defaults.h:
	I'm trying to push through some "standard" arch and OS defines,
	since they really help to be defined in many applications ports.
	The contents of defaults.h should be copied into your 
	13/orcacdefs/defaults.h file (or copied to that directory if you
	don't already have such a file).

	The macros defined in that file are
		__appleiigs__
		__GNO__
		__ORCAC_VERSION
		_ANSI_SOURCE		(if __KeepNamespacePure__ is defined)
		__KeepNamespacePure__	(if _ANSI_SOURCE is defined)

	Currently nothing depends on the _value_ of "__GNO__", just
	that it is defined.  The system header files which would have
	bad side effects if __GNO__ is not defined will bitch if this
	is the case.  These header files are ones where it was desirable
	to leave the BSD version in for reference.

	By putting __ORCAC_VERSION in defaults.h, we know that
		- it isn't defined for earlier Orca/C versions
		- it can be incremented

	Orca headers use __KeepNamespacePure__ and BSD headers use
	_ANSI_SOURCE.  We try to make them identical.

arpa/nameser.h:
	The non-standard field 'pr' (primary server required) in
	typedef struct {} HEADER has been removed, and it's storage
	moved to the 'unused' field.  The size of the structure and
	the offsets of the remaining members haven't changed.  This
	was a BSD change, not mine.

	The following macros have been added.  See the header for
	their meanings:
		__BIND
		HFIXEDSZ
		INT32SZ
		INT64SZ
		INADDRSZ

arpa/telnet.h:
	This file appears to have lots of changes, but I think
	that, given a recompilation of the relevent sources, they
	should be benign.  If not, then the descriptions below
	should give sufficient info to #ifdef out the problem parts.

	There are new TELOPT_* macros, values 35-39, inclusive.
	This affects NTELOPTS, TELOPT_LAST, TELOPT_OK, and the
	'telopts' character array.

	The following arrays are now terminated by a NULL pointer
		telopts
		telcmnds
		slc_names

	The following macros are also new:
		TELQUAL_INFO
		TELQUAL_REPLY
		TELQUAL_NAME
		LFLOW_*		(4 of them)
		MODE_SOFT_TAB
		MODE_LIT_ECHO
		MODE_MASK	(changed due to two previous macros)
		SLC_NAME_OK
		SLC_NAME		

fcntl.h:
	used to contain #defines for L_SET, L_INCR, and L_XTND.  These
	were renamed by POSIX 1003.1 to SEEK_SET, SEEK_CUR, and SEEK_END,
	respectively.  If the old macros are desired, they can be obtained
	by #including <unistd.h>.

machine/ansi.h:
	wchar_t (and therefore rune_t) have been changed from
	"unsigned short" to "int" to match the is*() definitions
	in <ctype.h>.  This shouldn't be a problem since there aren't
	yet any library routines that use these types.

machine/endian.h
	Note that under BSD 4.4, both BIG_ENDIAN and LITTLE_ENDIAN (and,
	for that matter, PDP_ENDIAN) are defined.  The way to test
	endianness is not
		#ifdef LITTLE_ENDIAN
	but rather
		#if (BYTE_ORDER == LITTLE_ENDIAN)
	I doubt that the kernel uses this macro ...

netdb.h:
	decl of inet_aton() removed; it should come from arpa/inet.h
	decl of struct rpcent removed; it should come from rpc/rpc.h

net/*:
	It appears that this directory is very much non-BSD.  I haven't
	touched it at all -- something in me says, "Danger, Will!".
	After things settle down, it might be worth it to make it
	closer to BSD, at least in the file names.  However, I'm not
	going to worry about it right now.

	For your perusal (if required) I've included the directory
	net.BSD which is the BSD 4.4 version of the net/* files.
	This subdirectory is not intended to be part of the GNO
	distribution.  (The net.BSD directory is in the NOTES directory.)

netinet/in.h:
	If the functions in_makeaddr() and in_lnaof() are used in the
	kernel, could you prototype them and reenable them where they
	appear in this file?  If not, please delete them and the
	enclosing #ifdef.

netinet/ip.h:
	BSD 4.4 uses a different value for IPTOS_PREC_ROUTINE than was
	in your original header.  I've got both in (one #ifdef'd), but
	could you delete the non-BSD one if it doesn't impact the
	kernel or GS/TCP?

pwd.h:
	struct passwd has changed in BSD 4.4.  getpwent and related
	routines have been updated, so any program that is using those
	routines to access the /etc/passwd file will be fine.  The
	file itself has not changed.

resolv.h:
	Name of "struct state" has changed to "__res_state" (I suspect
	this was done to keep from polluting the namespace).  The
	"options" field has changed from long to u_long, and the 
	structure has been lengthened.

	The new 'struct __res_state' has, however, been #ifdef'd out
	and you have your old 'struct state'.  Macro values haven't
	changed.  The functions you were using weren't prototyped, so
	I had to assume the BSD prototypes are correct.

	If you are willing to change to use 'struct __res_state', then
	check out the #define of '__RES' near the top of <resolv.h>.
	If you change then '__RES' should become an unconditional #define.

stdio.h:
	As of Orca/C v2.1.1b2, the definition of FILE has changed.
	The _pbk field has changed from
		int _pbk;
	to
		int _pbk[2];
	This is controlled via __ORCAC_VERSION defined in defaults.h

sys/ioccom.h:
	This header file now specifies that the high 3 (vice 2) bits
	of the uppper word are used to encode in/out status of the 
	parameter; is this compatible with the kernel?  (Grep for
	"IOCPARM_MASK" and look at the comments immediately prior to
	it.)

### sys/ioctl.h:
	I've included a "GNO-specific" section -- are these GNO-specific
	macros 	actually used anywhere?

	There are still some conflicts in this file with <sys/termios.h>,
	however they're not new -- they were in the headers you sent me
	as well.  One of these is the TOSTOP and associated macros.

sys/socket.h:
	It appears that the structures you used for "msghdr" and "sockaddr"
	have been deemed out-of-date in 4.4BSD; they have been renamed
	"omsghdr" and "osockaddr", respectively.  I don't know how you
	want to handle this; if necessary I guess one could use #ifdefs
	and #define sockaddr as osockaddr, et al.  I don't think the
	new structs should be outright deleted from the header.

	The field sequence, macro values, and so forth match your previous
	implementation.

	So that your routines are still getting the correct prototypes,
	I've used the macros __SOCKADDR and __MSGHDR in the header file
	prototypes; they're #defined right above the decls.

sys/termios.h:
	The names of two of the fields in struct termios has changed:
		ispeed	-->	c_ispeed
		ospeed	-->	c_ospeed

	See also the comments for <sys/ioctl.h>

sys/unistd.h:
	The values of some of the _PC* macros have changed.  I don't
	think this should matter since the functions pathconf(3) and
	fpathconf(3) haven't yet been implemented.

The following headers I don't believe are part of GNO, although they
were included with the headers you sent.  Please correct me if I'm 
wrong:
	cons.h
	console.h
	debug.h
	sprite.h
	sys/m16.ioctl -- perhaps part of GNO, but not a header

The following Orca headers were modified, but I don't believe that the
mods are required for GNO users.  (Are these fixes that should be
forwarded to Mike W?)	[asked 12 Jan]
	appleshare.h
	appletalk.h	<-- out of date as well
	control.h
	locator.h
	misctool.h

The following headers appear to be not only non-GNO, but obsolete:
	newshell.h
	shell2.h


Library Changes:
===============

There were lots of additions.

libc/sys/trap.asm	[formerly l2.asm]

	execve  renamed to _execve

	getpgrp renamed to _getpgrp

	kvm_getproc, kvm_nextproc, and kvm_setproc provided as alternate
	entry points into kvmgetproc, kvmnextproc, and kvmsetproc
	(respectively) since they were documented entry points in GNO v2.0.4

	setpgid is provided as an alternate entry point to setpgrp.
	The two are identical (under BSD), but the latter is considered
	obsolete.

	vfork added as alternate entry point to fork.

libc/sys/syscall.c
	The mkdir implementation could easily accept a mode parameter
	and thus become POSIX compliant.  Should the mode be added?

Manual Page Considerations:
==========================

NOTE NOTE NOTE:
		Currently there is a problem with the nroff package,
		and many of the man pages will not look right on the
		IIgs.  I'm working on an update of nroff.  Putting it under
		Insight has shown a significant number of memory trashing
		bugs (which are now gone).

undocumented(2):
	This man page lists the undocumented kernel calls.  I don't 
	know if all of these are supposed to _remain_ undocumented ...

kill(2):
	Please verify that description of operation with negative process 
	numbers matches implementation.  If there is no match, and
	the implementation cannot or will not be changed, please
	delete these paragraphs and change the STANDARDS section
	to read "The kill function is not POSIX 1003.1 conformant."

semaphore(2):
	I'm guessing at the behavior of scount; please verify it.

intro(2):
	The "DEFINITIONS" section of this man page is as yet verbatim
	from the BSD man page; I haven't had a chance to review it.
	If you have any comments, speak up ...


Tools
=====

mkso:
	I'm not done mkso yet (mkso is the program that creates
	the .so links required for the various manual pages).  I
	still have to make it check for the legality of file names
	on the current file system.  I also plan to make it such
	that one can place those .so links that require HFS on 
	another partition, and still have them find the sourced
	files.