Debian Codegraph @

sysdep.txt

raw
1 ##########################################################################
2 # This program is Copyright (C) 1986-2002 by Jonathan Payne. JOVE is #
3 # provided by Jonathan and Jovehacks without charge and without #
4 # warranty. You may copy, modify, and/or distribute JOVE, provided that #
5 # this notice is included in all the source files and documentation. #
6 ##########################################################################
7
8 Jove has two classes of ifdefs. Some are used to select system-dependent
9 features, others are to select Jove features. The former are defined in
10 sysdep.h, the latter in tune.h. This file describes the ones in sysdep.h.
11
12 sysdep.h is structured as a set of #ifdefs for different systems, each system
13 being identified by some unique symbol, recently, the result of the
14 uname command on an OS, for convenience. (e.g. Linux, Darwin, FreeBSD etc,
15 but previously, SYSVR4 for various System V Release 4 machines).
16
17 old/sysdep.h, not used by any Jove code, is a historical archive
18 of definitions that were once tested on various machines,
19 but have not been tested for the recent release, so it is
20 entirely possible that changes for other systems have caused
21 those older definitions to stop working.
22
23 We usually avoid symbols pre-defined by the compilers, they're too
24 hard to predict and often do not provide the granularity that's necessary to
25 differentiate between system versions or types. There's also sometimes
26 a variety of compilers with different pre-defined symbols. If the system you run is
27 included in sysdep.h, just use it. If not, select a symbol to define your
28 system (e.g. SOMEOS) and choose the appropriate system-dependent options that
29 characterize your systems terminal handling, process handling, header files,
30 etc from the list below. Using an existing system, or common group of
31 characteristics (XBSD, BSDPOSIX, etc) is often a good start.
32
33 NOTE: We've removed almost all the "#ifdef system-type" ifdefs from the body
34 of Jove code, replacing those with the feature ifdefs documented below.
35 This sort of approach is necessary in this day & age of hybrid systems.
36 If you're porting Jove to a new system, please follow the feature-based
37 approach and don't put "#ifdef system-type" ifdefs in the code.
38
39 From 5.x, Jove supports only POSIX termios.h
40
41 When Jove is tries to make file pathnames canonical. Handling of a ..
42 component must take account of symbolic links. All modern UNIXes have
43 symlinks. We don't yet know how to support MAC or WIN32 aliases.
44 HAS_SYMLINKS use readlink(2) to handle symlinks
45
46 In order to canonicalize SHAREDIR and LIBDIR paths relative to the
47 executable directory, Jove needs to figure out where the exectutable
48 ran from.
49 PNAME_PROC_SELF should be defined on Linux-like machines (or Debian Hurd)
50 since they have /proc/self/exe as a symlink to the
51 running executable path.
52 PNAME_GETEXECNAME should be defined on Solaris-like machines which have the
53 getexecname() function to return the running executable path.
54 PNAME_SYSCTL_OID should be defined on FreeBSD or NetBSD, with the oid
55 array that can be given to sysctl() to return the path
56 to the running executable.
57 If the above do not exist, it will use argv[0] and hope for the best.
58
59 Jove needs to make a number of temporary files. The traditional ways
60 of creating temp files are subject to race conditions allowing
61 security to be compromised on multi-user systems. The mkstemp library
62 routine avoids this problem, but isn't available on all systems. In
63 its place, Jove will make do by using mktemp. If this isn't
64 available, Jove will use an even poorer technique. The mktemp form
65 is safe if the open system call supports O_EXCL just right (it must
66 balk at symlinks).
67 NO_MKSTEMP work around lack of mkstemp
68 NO_MKTEMP work around lack of mktemp
69
70 In modern systems, the type mode_t is used for permission bits (in
71 creat(2), stat(2), and open(2)). In ancient systems, this was just int;
72 unsigned would have been better. Jove uses the macro jmode_t. If you
73 don't provide a definition, it defaults to mode_t.
74
75 Different environments have different memory and address space limitations.
76 Generally, these controls default appropriately.
77 NBUF Number of memory blocks allocated to cache for buffers.
78 LG_JBUFSIZ log-base-2(sizeof buffer block). Generally 9 or 10,
79 yielding blocks of size 512 or 1024 bytes. Each text line
80 in Jove is restricted to fit within a single block, so
81 larger is better. Also, larger blocks should reduce
82 the number of blocks transferred between the temp file
83 and RAM. Smaller blocks reduce the number of bytes
84 transferred and more efficiently use cache memory
85 (there would be more blocks in an identically sized cache).
86 JSMALL Intended for machines with small address spaces, for example
87 the PDP-11 and DOS 8086/8088. It drastically
88 reduces NBUF, cuts down LG_JBUFSIZ, and makes daddr an
89 unsigned short.
90 MALLOC_CACHE Causes the in-core cache for disk blocks to be malloced
91 rather than allocated as a static variable. This helps
92 environments where statically allocated things are placed
93 in one limited segment, but malloced things are placed
94 in separate segments. Examples include MAC and large
95 model x86. Remember that NBUF * ((1<<LG_JBUFSIZ) + overhead)
96 will probably have to fit within a single segment.
97
98 IPROCS is defined if interactive processes are to be supported. It
99 is defined in tune.h, implying that it is a matter of preference, at
100 least on UNIX systems. Unfortunately, in some cases control is
101 needed in sysdep.h (because it is a matter of feasibility). To
102 reflect this, if NO_IPROCS is defined in sysdep.h, tune.h will not
103 define IPROCS. Beware: doc/jove.rc (the standard system-wide rc file)
104 binds several process commands, so it will need changing if interactive
105 process support is not compiled in.
106
107 To multiplex between different processes and the keyboard (when IPROCS
108 is defined), define USE_SELECT.
109 USE_SELECT Have the select() system call. Almost essential!
110 USE_SELECT_H sys/select.h needed for FD_* macros. AIX and QNX.
111 Jove also uses select() for delays if available. Without select(),
112 the code is a kludge, but it may work...
113
114
115 Jove sometimes tries to find out if there is pending keyboard input.
116 There are too many different ways of doing this. Jove will use FIONREAD
117 if it finds that symbol defined by a header it includes. It will use
118 select if USE_SELECT is defined. Older systems may support
119 fcntl(... O_NDELAY); POSIX.1 systems should support O_NONBLOCK.
120 NONBLOCKINGREAD use O_NDELAY/O_NONBLOCK to test for pending keyboard input
121
122
123 If IPROCS is defined in tune.h, one of the following two must be defined.
124 If your system supports neither PTYS nor PIPES, don't define IPROCS unless
125 you feel in the mood for very serious hacking.
126 PTYPROCS Use pseudo-ttys. BSD and most modern UNIXes.
127 PIPEPROCS Use pipes for interactive processes. Older UNIXes.
128 Don't forget to set PORTSRVINST in Makefile.
129
130 If PTYPROCS is defined, then one of the following must be defined. Or
131 add your own code in iproc-ptys.c. SVR4_PTYS are more secure than
132 BSD_PTYS (the BSD weakness is described below). SVR4_PTYS are also
133 known (at least in the LINUX world) as UNIX98 PTYS. They are part of
134 "The Single UNIX Specification", Version 2.
135 SVR4_PTYS SYSVR4 pty allocation. Use /dev/ptmx, ptsname, grantpt, etc
136 BSD_PTYS traditional BSD ptys.
137 IRIX_PTYS Irix 3.x onwards -- open a master device, then fstat to get
138 major and minor numbers.
139
140 WARNING: On BSD systems, there is a dangerous security hole in the PTY
141 system. Although JOVE (or any other non-privileged program) can
142 allocate a PTY, it cannot change the ownership or permissions to
143 prevent other processes run by other users from mucking with the same
144 PTY. An example of such mischief is that someone else could trick
145 your JOVE into running a shell command for him but as you! The
146 traditional way to allocate a PTY is to search through search through
147 /dev/pty[p-s][0-9a-f] for a free one, and use that. Modern BSD
148 systems have added a new library routine "openpty(3)" which could be
149 made to close this hole, but this hasn't happened at this time (2001
150 March 21). In anticipation of such a fix, JOVE can be made to use
151 this routine. Currently, the only advantage is that when JOVE is run
152 by the superuser, some versions of BSD do manage to close the hole. A
153 disadvantage is that -lutil must be added to the link command because
154 openpty is in libutil.
155
156 OpenBSD 3.5 has closed this hole (2004).
157 USE_OPENPTY use the new BSD openpty(3) routine (OpenBSD, NetBSD, MacOS X Darwin)
158 HAVE_LIBUTIL_H use <libutil.h> instead of <util.h> (FreeBSD)
159 HAVE_PTY_H use <pty.h> instead of <util.h> (Cygwin, glibc, Interix, OSF/1 4 and 5)
160
161 Certain early SVR4 systems have a buggy grantpt library routine that
162 is used if PTYPROCS is defined. A symptom is that the "shell"
163 command will always fail with a [grantpt failed] message. System V
164 Release 4.0, and Solaris 2.0 (but not Solaris 2.3) and Digital UNIX 4.0
165 have this bug. It turns out that this bug is documented as a feature
166 in "The Single UNIX Specification", Version 2!
167 GRANTPT_BUG Define this to enable a work-around.
168
169 Certain systems, for example NetBSD (at least 7.x and 8.x),
170 IRIX 4 and IRIX 5.3, define the symbol TIOCREMOTE but don't
171 implement this ioctl correctly. A symptom is that the
172 eof-process command will not work.
173 NO_TIOCREMOTE Define this to avoid using TIOCREMOTE even if the
174 system defines it.
175
176 Certain systems, for example IRIX 5.3, define the symbol TIOCSIGNAL
177 but don't implement this ioctl correctly. A symptom is that the
178 interrupt-process command will not work.
179 NO_TIOCSIGNAL Define this to avoid using TIOCSIGNAL and TIOCSIG even
180 if system defines them.
181
182 Certain systems, for example HP/UX 9, don't seem to send EOF to the master
183 side of the pty when the slave side shuts down. On these systems, Jove
184 should be told not to wait for EOF:
185 NO_EOF_FROM_PTY Define this if your system fails to signal EOF to pty master
186
187 To deal with SUBSHELL and IPROCS (both in tune.h), define one of the
188 following:
189 POSIX_PROCS Supports POSIX processes, waitpid()
190 If POSIX_PROCS is not defined, Jove uses wait(). (old UNIXes)
191
192 Signal handling varies between systems. The original UNIX signal mechanism
193 is unsafe -- if a second signal is received soon enough, the program will
194 crash. Furthermore, there is no mechanism for a process to request that
195 signal delivery be held temporarily. BSD, System V, and POSIX have each
196 provided better but different facilities. Without safe signals, Jove might
197 crash, although this is not common. Jove will use signal holding to more
198 gracefully handle SIGINTs while starting processes; otherwise those SIGINTs
199 will be ignored. The feature select macros, in decreasing order of
200 preference are:
201 POSIX_SIGS Use POSIX's safe sigaction(); use sigprocmask() for signal holding.
202 USE_SIGSET Use sigset(), 4.2BSD's safe signal mechanism.
203 Use sighold() and sigrelse() for signal holding.
204 BSD_SIGS Use 4.x BSD's safe signal(); use for sigsetmask() for holding.
205 If none of these symbols is defined, unsafe normal signals are used (except
206 on BSD systems, where the normally unsafe signal() is in fact safe).
207
208
209 JOB_CONTROL System supports job control (SIGTSTP, ^Z etc. for pause-jove)
210
211 USE_VFORK system has a vfork that is much faster than fork. This
212 capability should be nuked (any modern copy-on-write
213 memory implementation should be able to do fork almost as
214 fast as vfork)! It is only believed to be useful for
215 architectures without an MMU (we welcome test reports)
216
217 The following are only needed for IPROCS.
218 BSD_SETPGRP setpgrp takes two arguments. If this is not defined,
219 assume System V setpgrp with no arguments.
220 USE_KILLPG Uses the BSD killpg() system call. If this is not defined,
221 Jove assumes that kill(-pid, ...) is equivalent (SysV).
222
223
224 If F_COMPLETION is defined, then Jove needs to be able to scan directories.
225 By default, Jove assumes the system has "struct dirent" and "dirent.h".
226 If not, define one of the following
227 BSD_DIR has "struct direct" and "sys/dir.h". BSD4.2. (maybe 4.1?)
228 DIRENT_EMULATE emulate dirent routines by open()ing and read()ing the
229 directory.
230 M_XENIX Support for some versions of XENIX, dealing with
231 peculiarities of directory handling. Not recently tested.
232
233
234 If F_COMPLETION is defined, and you want ~username to be expanded, then
235 you may need to define the following, especially on systems running YP/NIS,
236 or using a database form of the password file.
237 USE_GETPWNAM has the getpwnam() system call. Just about every modern
238 Unix.
239
240
241 Choose the type of signal handler. If you don't define these, Jove
242 defaults to "void" and "/*void!*/".
243 SIGRESTYPE the return type of signal handlers. "void" on most modern
244 systems, "int" on older systems.
245 SIGRESVALUE the return value of signal handlers. "/*void!*/" on systems
246 where SIGRESTYPE is "void", usually 0 on systems where
247 SIGRESTYPE is "int".
248
249
250 Either of following two is useful to the "recover" program, but not both.
251 USE_UNAME has the uname() system call. True on System V and POSIX
252 and most hybrids.
253 USE_GETHOSTNAME has gethostname() system call. True on most BSD machines.
254
255
256 NO_STRERROR If you do not have the strerror() routine. Needed for
257 pre-ANSI systems (SunOS older than 4.1, BSD, older UNIXes)
258 With this defined, Jove provides an emulation using
259 sys_errlist, which should work on most UNIXes.
260
261 USE_FSYNC Have the fsync() system call. True on just about all modern
262 UNIXes. Used to ask the OS to really flush the file to disk.
263
264 Jove supports 7-bit or 8-bit character sets. It has a wired-in
265 notion of what each kind of character is, but it can use the
266 system's classification of control characters.
267 NCHARS the number of distinct character codes. This defaults to 256
268 but can be set to 128 for 7-bit character sets.
269 USE_CTYPE use the system's <ctype.h> functions. If this is
270 defined and these functions only work for 7-bit
271 characters, be sure to define NCHARS to be 128
272 NO_SETLOCALE define if you wish to define USE_CTYPE but the system
273 has no setlocale routine.
274 ISO_8859_1 use wired-in tables reflecting the characteristics of the
275 ISO 8859-1 character set (Latin1) (USE_CTYPE is better if
276 it works).
277 For the IBM PC under MSDOS, look below for the description of CODEPAGE437.
278 There is a wired-in table for the Macintosh used if MAC is defined.
279
280 DEBUGCRASH Do not trap on SEGV, BUS signals, useful for running Jove
281 under a debugger (e.g. gdb, dbx)
282
283 DEFINE_PC_BC_UP_OSPEED
284 Certain variables used by termcap/terminfo are
285 declared in the library on almost all systems. For
286 those systems that don't define them, this macro
287 enables declarations within Jove. Needed for HPUX
288 and possibly other SysV Rel.2 machines. If you get
289 messages like "ospeed undefined" when linking, try
290 this.
291
292 USE_INO use the inode number (and device number) to tell if two
293 paths refer to the same file or directory. Automatically
294 defined for UNIX. Supported for MAC too.
295
296 USE_EXIT Normally, Jove exits by calling _exit, to avoid stdio.
297 When this symbol is defined, exit() is used instead.
298 This is needed when profiling Jove or running it under
299 debugging tools like purify.
300
301 UNIX This is automatically defined if we're none of MAC, MSDOS
302 or WIN32.
303
304 TERMCAP Support display diversity via termcap database.
305 This is automatically defined for UNIX.
306
307 TERMINFO Support for System V variant of TERMCAP. TERMCAP
308 must also be defined. This differentiates between
309 tparm and tgoto.
310
311 JTC Simple builtin-termcap emulation, avoids need
312 for external library dependency on termcap/terminfo/*curses*.
313 TERMCAP must also be defined. The OS must support select(),
314 which is used for timing delays.
315 Only works on vt[123]NN or compatible terminals, or
316 emulators like xterm/rxvt/st/vte etc. The environment
317 variable JOVEVT can be set to the level of emulation,
318 the number of the DEC terminal (e.g. 100 for vt100,
319 102 for vt102, etc, and 999 or "alt" for xterm-like
320 emulators that support the alternate screen.
321 99 means ordinary minimal ANSI X3.64/ECMA-48 emulation,
322 the minimal cursor movement and screen clearing capabilities
323 needed for a screen editor. Even most ancient vt100-clones
324 and half-hearted emulators should be able to support this.
325 100 and above have visible bell, scrolling region, arrow keys.
326 102 and above have insert and delete chars and lines.
327 125 adds a meta-key.
328 320 adds multi-line scroll or pan forward/backward (SU/SD)
329 999 (aka alt) have alternate screens.
330
331 NCURSES_BUG Work around the non-standard meaning of insert character
332 capabilities in the termcap and terminfo databases
333 distributed with ncurses. Probably needed for FreeBSD,
334 NetBSD, and LINUX. Probably safe for all others (except
335 if you use a Datamedia 2500 terminal). We automatically
336 define this for UNIX.
337
338 Jove has been built and tested on PC-compatible computers
339 under a couple of compilers and environments, but is neither
340 developed nor regression tested on them, so it might be in
341 active use there. The following defines are primarily
342 used to tailor the characteristics of various PC
343 environments and/or differentiate them from the Unix or MAC
344 variants of Jove.
345
346 WIN32 indicates Jove running as a Console app under the WIN32
347 (Windows NT, 95, 98, 2000, XP, etc)
348 Tested on Windows 7 for 4.17.
349
350 OWCDOS Open Watcom compiler for MSDOS. This has been tested for 4.17
351
352 MSDOS MSDOS or MSDOS-like system. Only tested on IBMPCDOS in recent
353 memory, but worked on the DEC Rainbow ant Atari ST once.
354
355 IBMPCDOS Indicates MSDOS on an IBM PC-Compatible hardware platform.
356 This enables hardware-specific characteristics of Jove on
357 this platform, such as the screen and keyboard interface.
358
359 The following characteristics are currently enabled only in the MSDOS
360 and WIN32 environments but could be enabled in other environments if
361 it made sense to do so.
362
363 FILENAME_CASEINSENSITIVE indicates that Jove should ignore case
364 when comparing filenames. This should only be defined when
365 building Jove in an environment with this characteristic,
366 e.g. MSDOS or WIN32. Note: this does not imply that filenames
367 are monocase; they may be (as for MSDOS) but may not be (e.g.
368 for WIN32).
369
370 DIRECT0RY_ADD_SLASH indicates that Jove will display a slash at the end
371 of directory names when browsing for a file (i.e. when a ?
372 is entered during Jove's prompt for a file name). Define
373 this only if it can be done cheaply in the jscandir
374 implementation (and also set up jscandir to do so).
375 It is presently defined for MAC, MSDOS, and WIN32.
376
377 MSFILESYSTEM enables certain filename parsing features in Jove to support
378 Microsoft's manner of organizing a filesystem. This includes
379 one-letter device names, use of backslash as a directory
380 separator, and avoidance of a "dot" as the first character of
381 a filename (as in .joverc).
382
383 EOL character to recognize and use as end-of-line when loading or
384 saving text files. Defaults to '\n'.
385
386 USE_CRLF tells Jove to recognize and use CR/LF as end-of-line when
387 loading or saving text files. A bare LF will still be
388 recognized on input. EOL should be left as the default '\n'.
389
390 PCNONASCII The IBM PC keyboards have a number of keys that don't
391 generate ASCII characters (for example, function keys).
392 Other systems use escape sequences or control characters
393 to encode these keys. For the PC, we use a special
394 code (0xFF) as a prefix for the scan-code generated
395 by the key. PCNONASCII is both the feature selector,
396 and, if defined, it has the value of this prefix.
397
398 NO_JSTDOUT This suppresses stdio-style buffering for screen output
399 or the use of file descriptor 0 or /dev/tty.
400
401 CODEPAGE437 This is the name of the "ordinary" character set supported
402 by IBM PC displays. It is described in the appendix of
403 "Microsoft MSDOS Operating System 5.0 User's Guide and
404 Reference" as supporting USA English.
405
406 PCSCRATTR Exploit IBMPC screen attributes. Enables variables
407 text-attribute, mode-line-attribute, and highlight-attribute.
408
409 Jove was once ported to the old (pre OS X) has not been well
410 tested, nor does it follow Mac conventions. Perhaps it
411 should be considered a proof of portability.
412 MAC Select all the Macintosh-specific code.