TUHS

tuhs@tuhs.org

29 participants
6557 discussions

by helbig＠informatik.ba-stuttgart.de

Hallo, Most, if not all, of the V6-docs was distributed with V6 as troff sources. At http://www.ba-stuttgart.de/~helbig/os/ you'll find postscript versions of these docs. Have fun, Wolfgang

22 years, 10 months

Re: Weinberger stencil? (was: rtm)

by norman＠nose.cs.utoronto.ca

This is certainly non-technical UNIX history, which is not to say it isn't interesting. I can sharpen up a few details of Dennis's account. Peter was already a department head when I first visited the Labs in early 1984. I believe his face was already a favourite test image for various graphics experts, but the cult of the face didn't really get started until the following year. In particular I think it was in the summer of 1985 that Tom Duff thought of the deathstar transform (turning a picture into variable- width horizontal stripes, as the AT&T logo to a highlighted sphere). Certainly it was later that year that the much-bigger-than-life image appeared on the water tower: my calendar file still says sep 16 btl water tower 1985 Peter was still a department head at that time; he didn't climb further into management until about 1990. As I recall, the water tower remained painted for a couple of days. A two-man team from the Physical Plant department finally covered it over: one man in overalls wielding paint, another in suit and tie watching to be sure no trace remained. Lest people get the wrong idea, Peter took no offense at the overuse of his face. In fact a few years later he agreed to have a plaster cast made. Someone (Duff?) then made a latex positive from the plaster negative, intending to digitize it somehow into a three-dimensional model. I don't know if that ever happened, but I did borrow the latex one day, used it to generate another negative in ice, and cast a large chocolate truffle which I then set out in the UNIX Room (as the group's common terminal room was called) for all to enjoy. That may have been the only really interesting use of the 3d face. In any case the plaster cast was presented to me when I left the Labs in 1990, and I still have it, though I haven't done anything with it since. There were also some smaller stencils made of the same deathstar- Peter face. (In fact I have it on good authority that the big one was made by projecting one of the smaller ones on a wall.) When Bell Labs bought a Cray X-MP in 1986 or 1987 (my records aren't that complete), one of our group made several visits to Cray to get a head start on a special network interface we would need. He took along one of the small stencils and put a few Peter faces on panels that were normally covered up when the machine was running. (The Cray was to be shared by Research and the Comp Center, and the Comp Center were a bit stuffier.) To everyone's surprise, when the machine arrived it bore no extra decorations. Presumably Cray shipped the painted system to another customer; we never found out who. The Computing Science Research Center was a fun place to work. Norman Wilson Toronto ON

22 years, 10 months

Re: Weinberger stencil? (was: rtm)

by Dennis Ritchie

Lehey wondered: > .... can > you shed any light on the "Peter Weinberger stencil" incident? ... > Somebody came across the idea of > making a large stencil of his face in death-star like technology, > and used it to paint an image of him on a nearby water tower. > Allegedly the costs were charged to Peter's department. > Some years later, this stencil arrived in Greg Rose's office in > Australia from an anonymous sender. Greg has a suspicion who the > sender was, but no proof, so he doesn't want to comment. He gave it > to our own Warren Toomey, who still has it in his garage. > At some point, Peter Salus suggested that the image was of Rob Pike... I could recover some of the dates, but not accurately from memory. Weinberger was promoted, first to department head, then to being director of a newly-created but next-door center, then to our own executive director. This would have been mid-late 80s, early 90s. He was being groomed, it appears. Shortly before trivestiture, 1994ish, he went to the business part of AT&T, possibly in preparation for coming back to a higher management position at the Labs. When the Lucent/AT&T split occurred he was somewhat caught on the AT&T side. He ended up leaving AT&T and going to a financial quant company. His image was particularly striking, and was used to kid him in various ways, e,g, as a default image in mail icons. The image rendering his face with the Deathstar styling was done by Tom Duff, and it appeared, for example, on T-shirts worn publically at venues like Usenix and elsewhere. Other versions of it appear inscribed in concrete now buried beneath floors at the Labs. There is a bitmap version (rendered in 1cm magnets) of the full image, not death-starred, high on a steel wall above a landing on a nearby stairwell. The large stencilled image of the Deathstar/PJW rendition did indeed appear suddenly one day on a water tower; it must have been about 10 feet tall. Kernighan had a photo of it, and Gerard Holzmann just scanned it: http://www.cs.bell-labs.com/who/dmr/pix/watertower.jpg It was painted over quite rapidly, a couple of days at most. (The tower itself is now gone, though not because of this.) The image was certainly not of Rob Pike. After this happened, a voucher was pinned up on a communal corkboard, claiming expenses for several cans of blue spray paint. The voucher was signed by one G. R. Emlin, a fictitious personage with his (later her) own history. Attached to it was a handwritten note from our then Executive Director (Vic Vyssotsky) saying approximately as follows: Unfortunately, this voucher cannot be approved by me; I am not empowered to approve Real Estate improvements. If Mr. Emlin would like to arrange a transfer to the Building and Grounds department, I would be happy to assist. So: who did it? If Greg Rose suspects certain aviation-inclined buddies, I in turn think his suspicions are likely to be well-founded. I managed to retrieve the image used to create the stencil; it's now linked-to near the bottom of http://www.cs.bell-labs.com/10thEdMan/v2pix.html Dennis

22 years, 10 months

C reference manual

by Tony Finch

I'm looking for a copy of the C reference manual from some time between the 6th Edition (1975) and the first version that came with 4.3BSD (1986). The stuff in the TUHS archive mostly seems to be missing the documentation sets, or in the case of the earlier BSDs they are ommitted for copyright reasons. There are some tutorials dating from about 1979 but they aren't much use. Any help would be appreciated. Tony. -- f.a.n.finch <dot(a)dotat.at> http://dotat.at/ DOGGER: NORTHEAST 6 TO GALE 8 BACKING NORTHWEST 4 OR 5. RAIN OR SHOWERS. MODERATE OR GOOD.

22 years, 10 months

rtm

by A.P.Garcia

I just recently picked up a copy of a book that's been out for some time, _Cyberpunk_ by Katie Hafner and John Markoff. The last chapter is about Robert T. Morris, Jr. and the worm incident (which in itself, I think, is an important event in Unix history). The book contains some interesting details, including some Unix folklore that I haven't seen anywhere else. For instance, RTM Sr. had a terminal at home, as did other members of the CSR group at Bell Labs. So a number of their kids had accounts! RTM Sr. comes off as a very likeable fellow, btw. At the Atlanta Linux Showcase in 1999, Norm Schryer gave a keynote speech, in which he told an amusing anecdote about Morris Sr. (I may be slightly off on some details; such is oral history): Morris, he said, was the kind of guy who always liked to tinker with things, and if an object had buttons, Morris just had to push them. In fact, sometimes Morris was just a little too quick with his fingers. On one side of a machine room was the light switch, and on the other side was the power to the machine. On at least one occasion, you guessed it -- Morris hit the wrong switch. Some people hung a disk pack that got ruined around his neck, and someone put up a big sign as a reminder: "THIS IS THE WEST WALL!" :-)

22 years, 10 months

Re: rtm

by Dennis Ritchie

Garcia is correct to praise the Hafner/Markoff account of the worm incident. There were some details about the kids' accounts and exploits that Markoff decided to elide; by the time he wrote that chapter he had become rather sympathetic with the Morris family. In 1995 another big incident occurred: the exploitation of the SYN TCP-connection takeover attack (Mitnick etc.) Markoff got another front-page NYT story out of this (and a book with Shimomura). I sent mail to Markoff at the time of the newspaper coverage reminding him that RTM had discovered the basic attack in 1985 (see CSTR 117 at http://www.cs.bell-labs.com/cm/cs/cstr.html ); while here during a summer. Markoff replied in part, >Interesting how often RTM figures, one way or another, in your front-page >stories, and of course the [Cyberpunk] book.... > > Dennis Ritchie yes, this is true. you know i sat there on sunday for about ten minutes and thought about whether i should include rtm in my story - it would obviously have spiced it up. i finally decided not to on the grounds that 1. i have done enough to mythologize him for one decade 2. he is probably entitled not to be dragged through all this again. i still wonder whether i did the readers a disservice... Incidentally, "RTM Sr." was (while here) "rhm" by login name, and always called Bob; I don't think he actually has a middle name (at least I don't know it.) I think it's like Harry S Truman. RTM is called Robert, and never used Jr. About > [Bob] Morris, he said, was the kind of guy who always liked to tinker with > things, and if an object had buttons, Morris just had to push them. > In fact, sometimes Morris was just a little too quick with his fingers. > On one side of a machine room was the light switch, and on the other > side was the power to the machine. > On at least one occasion, you guessed it -- Morris hit the wrong switch. > Some people hung a disk pack that got ruined around his neck, and someone > put up a big sign as a reminder: "THIS IS THE WEST WALL!" I suspect that we may be dealing with the "Schryer filter" regarding some of the details. Norm S. was right about Bob's being an aggressive investigator and fiddler, but I don't connect the west-wall sign with Morris in particular, but my memory could be failing too. Norman Wilson might have been around for advent of the sign. In the event, it had more to do with circuit breakers labelled in small print "east wall" and "west wall" and someone choosing the wrong one. Dennis

22 years, 10 months

RE: [pups] Ultrix-3.1 boot tape inside the PDP-11 distribution directory

by Fred N. van Kempen

Gregg, > Question 1) Has anyone actually followed the instructions and > description of same, found inside the readme file found in the > directory? Yes. They are a cut-and-paste log of my actual screens, although I can't remember exactly what was in the file. > Question 2) Was this on actual hardware? Or inside the Simh simulator? > Or even with one version of E11? I did installs on real hardware (MicroPDP-11/23 and MicroPDP-11/83), and on Ersatz-11 (V3.0) for DOS. > In my case this will be inside the Simh simulator, and I am basically > working straight from the beginning. If all goes well, I'll move it to > the E11 one. Ultrix-11 runs fine on SimH, with the "downs" that because SimH does not do detailed and correct CPU emulation, Ultrix gets confuzed every now and then, which does not happen with E11. I am preparing a new (V3.2) release of Ultrix-11 which has major changes, including: - full system regeneration off single source tree - full RAxx support - addition of VTserver, TDU and compress - compressed manual pages and documentation - Y2K support (not just date(1) ;-) The installation procedure has also changed to a more modern style. I don't have much time right now, so progress is slow. The above is "done", though. If you need help with Ultrix-11, pse contact me off-list. --fred

22 years, 10 months

[pups] Ultrix-3.1 boot tape inside the PDP-11 distribution directory

by Gregg C Levine

Hello from Gregg C Levine This is both my first post from this address, and a couple of questions. Question 1) Has anyone actually followed the instructions and description of same, found inside the readme file found in the directory? Question 2) Was this on actual hardware? Or inside the Simh simulator? Or even with one version of E11? In my case this will be inside the Simh simulator, and I am basically working straight from the beginning. If all goes well, I'll move it to the E11 one. ------------------- Gregg C Levine hansolofalcon(a)worldnet.att.net ------------------------------------------------------------ "The Force will be with you...Always." Obi-Wan Kenobi "Use the Force, Luke." Obi-Wan Kenobi (This company dedicates this E-Mail to General Obi-Wan Kenobi ) (This company dedicates this E-Mail to Master Yoda )

22 years, 10 months

Re: [TUHS] rtm

by msokolov＠ivan.Harhan.ORG

Jeffrey Sharp <jss(a)subatomix.com> wrote: > Yes, I believe I am somewhat younger than most the very respectable members > of this group. :-) I'm about the same. My timeline: 1979 born 1988 first computer: Soviet PDP-11 clone, first language: PDP-11 assembly 1995 first introduced to UNIX 1996 first live encounter with a VAX 1998 started maintaining my own version of VAX UNIX 2000 fully converted to it 2002 thinking about designing and building a new VAX CPU on an FPGA MS

22 years, 10 months

Actual names of boot images versus names listed in readme file for boot_images

by Gregg C Levine

Hello from Gregg C Levine I found out, on my system, and borrowing the Cygwin tools for file manipulation, the actual file name for .2,9BSD_rl02_1145.gz, it is rl02_2.9BSDroot, so I used that name in place of the one suggested inside the readme file. It works the same way. However, this is just the root collection. Is there any other pack available that contains the other members of the entire 2.9BSD system that provided us with this one? Also this was done with version 2.9-11 of Simh. So, when you get a chance, Warren, you can update the readme, and upload the appropriate file to the directory on your server. Oh yes, this came from a mirror of your site, its the one on ftp.tux.org Gregg C Levine drwho8(a)worldnet.att.net "Oh my!" The Second Doctor's nearly favorite phrase.

22 years, 10 months

Pack found in Tim Shoppa distribution but not listed

by Gregg C Levine

Hello from Gregg C Levine This is something that is totally different then what I first reported on regarding this distribution. In the readme for this one, it mentions everything list inside the directory, except the one marked down as "Unlabeled", and it originally came on a RL02 type diskpack. It is not listed in the Readme. Obviously it is what it says it is, an unlabled diskpack that Tim recovered the same day as the others, and those are indeed present, and listed. Except obviously the one that I first reported, that one isn't mentioned, and not there. That subject is done. I am just reporting on "Unlabeled", as far as everyone is concerned, is there anything on it? Or is it an empty pack? Gregg C Levine drwho8(a)worldnet.att.net "Oh my!" The Second Doctor's nearly favorite phrase.

22 years, 10 months

Re: [TUHS] Can someone advise me regarding a gui for UNIX

by Aharon Robbins

Another reason the 5620 was botched so badly was that AT&T wanted >= $2000 for the development kit (read: C compiler and libraries) for it. Not a good way to get lots of 3rd party application developers on your bandwagon. I used one for a year or so; it was the first windowing system I'd used and the only one I've really liked. For about 10 years I've been using 9wm, which gives a similar feel (at least to me). Those who want to go all the way should adopt 9term as well. (I generally run xterm + bash these days, although for a long while it was 9term + es/rc.) Somewhere, I have an X version of the 5620 font. I found that it wasn't so pretty. I've been using the pelm-latin1-9 font from the sam distribution for years. Norman forgot to mention that the most long-lived split-design application is Rob Pike's sam editor, still available for X11 and still in use on Plan 9. Arnold

22 years, 10 months

Re: Can someone advise me regarding a gui for UNIX

by Brian S Walden

Another hurdle for the 5620/630/730 lines of terminals was when I tried getting software support. Teletype being a mostly a "dumb" terminal manufacturer never considered them more that a way to have multilple 80 char x 24 line terminals on one display. I had difficulty in conveying to them that it was a computer in its own right and you could program it. The marketing was probably just as limited in scope. Another blow for the BLIT portion on the terminal came when you cound get an external cartridge for the 730 that turned it into an X-terminal. I got mine in 1991 and then rarely used layers after that. -B

22 years, 10 months

Re: Can someone advise me regarding a gui for UNIX

by Dennis Ritchie

Norman Wilson's account of the Jerq/Blit etc. is quite complete and correct, though there was some recycling of names. 'Jerq' actually was used quite early, when Pike got interested in bitmap graphics. The name was a takeoff on the Three Rivers Perq, which he (and I) saw at Lucasfilm Ltd. while attending an early Usenix. Blit was the slightly more PC version (suggested either as part of BitBlt or "Bell Labs Interactive Terminal). The originals used the Motorola 68000, and part of the development messup was AT&T Computer systems' decision to switch to the WE32000 processor with consequent delay for porting and reworking. The earliest versions were not quite as wonderful in practice as Norman suggests for the later ones. They were built by the Teletype corp. model shop (in quantity of a few hundred) and downloading the OS took several minutes at 1200bps--necessary at startup, since they didn't have a ROM for the whole thing, just enough for doing a download. They were also static electricity antennas! Many is the time that I would shift in my chair, then touch the keyboard, only to have the terminal reset itself. I developed the habit of putting my hand on the heavy steel case before moving around. On the other hand, the basic idea was architecturally right (and the later commercial versions were not so subject to static, and had ROM for the OS). They were even nicer at 9600bps. It's good to know that Norman is still using his. Dennis

22 years, 10 months

Re: [TUHS] Can someone advise me regarding a gui for UNIX

by A.P.Garcia

> I've been using this window system more or less daily since August 1984, > though only at home since I left Bell Labs in 1990. (I am using it to > type this message.) ! what other hardware and software do you run, if you don't mind my noseyness?

22 years, 10 months

re: c coding standards

by A.P.Garcia

> Not to be overly picky, but aren't there two copies of everything. yes, sorry. that's just how it was posted to usenet.

22 years, 10 months

Re: [TUHS] c coding standards

by Carl Lowenstein

> From: "A.P.Garcia" <apgarcia(a)uwm.edu> > To: tuhs(a)minnie.tuhs.org > Subject: [TUHS] c coding standards > Date: Fri, 11 Oct 2002 01:52:08 +0000 > > check out this old post I found on Google Groups. > this kind of stuff makes me giddy. :-) < 2288 lines deleted > Not to be overly picky, but aren't there two copies of everything. carl -- carl lowenstein marine physical lab u.c. san diego clowenst(a)ucsd.edu

22 years, 10 months

Re: [TUHS] Can someone advise me regarding a gui for UNIX

by norman＠nose.cs.utoronto.ca

22. Pike, R. "The Blit: A Multiplexed Graphics Terminal". _AT&T Bell Laboratories Technical Journal 63_, 8 (Oct. 1984). Rob described an earlier version of the Blit work in a USENIX talk at USENIX in January 1982 (Santa Monica CA). So far as I know it was just a talk, no paper, though he showed a canned demo on video tape. For those who don't know it, the Blit (in later versions called the Jerq; in official product version, the AT&T 5620 DMD terminal, and later the 630 and 730) is a separate terminal with a bitmapped display, keyboard, and mouse. The window system runs in the terminal; a multiplexed-channel protocol (one channel per window) is used to communicate with the host computer; a (user-mode) multiplexer program on the host passes data for each channel to and from an appropriate local process (group), one per channel. Creating a new window in the terminal tells the multiplexer to create a new process in the host. By default the window is just a terminal (and the process is a shell), but it is possible for a host program to download a program into the terminal (where it can get at the screen and mouse directly) to act on its behalf just for its own window; that's how graphical programs work. This often requires programs to be split into front and back ends, but often that turns out to be a good idea anyway, keeping user-interface work and file-manipulation and computation separate. It also means much less communication bandwidth is needed; in fact the communication line is RS232 (what else would you expect in 1982?). It worked fine, even at 1200 bps, except when a large graphical front- end program had to be loaded, but people tended to load such programs once and keep them running. I've been using this window system more or less daily since August 1984, though only at home since I left Bell Labs in 1990. (I am using it to type this message.) It is Spartan by modern standards--menus are short and to-the-point, windows are not surrounded by fancy borders and icons, there is no `desktop' or `graphical user environment'--it's just good old UNIX in multiple windows, with a terminal window that makes good use of the mouse for local editing, and provision to run fancier programs when necessary. It wouldn't work well for graphics-heavy work unless the communication line could be greatly sped up--a web browser would be hard to make work well unless all the pictures were left out. But it's well thought out, with a nice balance between spareness and function. I still like it better than any other window system I've seen; even Rob's more recent work in Plan 9 seems to me over-elaborate by comparison. I also like much better the overall model that the terminal is a client rather than a server; X11 always seemed inside-out to me. I am still disappointed that the process of turning the Blit from a research tool to a salable product was botched so badly. If memory serves, not only did it take several years longer than it should have done, but when the 5620 hit the streets in early 1984 it cost a mere $6000, which even in those days was outrageous for a terminal. (None of this was Rob's fault so far as I know.) If things had gone better, the UNIX windowing world might have turned out quite different. Norman Wilson Toronto ON

22 years, 10 months

c coding standards

by A.P.Garcia

check out this old post I found on Google Groups. this kind of stuff makes me giddy. :-) -=-=-=- Message-ID: <bnews.mit-vax.149> Newsgroups: net.sources X-Path: utzoo!decvax!harpo!eagle!mit-vax!mp From: mit-vax!mp Date: Tue Jun 29 08:07:31 1982 Subject: C coding standards X-Google-Info: Converted from the original B-News header Posted: Sun Jun 27 18:24:20 1982 Received: Tue Jun 29 08:07:31 1982 In my message in net.misc about coding standards, I offered to send out the Stanford Network Graphics project's C style sheet. Since almost everyone who responded to my query requested a copy of that document, I decided to post it to the net. In fact, thanks to JBrookshire@USC-ECLB, I now have 3 different C style standards to give you. Each is separated by a line of "*********"s. Mark Plotnick, MIT ************************************************ INGRES CODING CONVENTIONS FOR C/UNIX PROGRAMMING University of California, Berkeley "The Ingres data base system encompasses about 75,000 lines of code in the programming language `C' and runs on top of the Unix operating system. Over the past six years, Ingres has evolved into a functionally complete and usable prototype. Development required 25 to 30 programmer-years by a total of 19 people, and the systems is now in use at over 125 sites around the world." Allman, Eric.; and Stonebreaker, Michael "Observations on the Evolution of a Software System." COMPUTER 15, 6 (June 1982), 27-32. The following represents the current C coding conventions that have evolved from and during the development of the Ingres system. This document has been provided by Joe Kalash of Berkeley <INGVAX.kalash at Berkeley> in response to a general enquiry distributed via Arpanet BBOARDS. /* ** CODE_CNVNTNS.C -- A Program to Display the INGRES Coding Style ** ** This hunk of code does virtually nothing of use. Its main ** purpose is to demonstrate the "official" ingres coding style. ** ** This demonstrates comments. There should be a block comment ** at the beginning of every file and/or procedure to explain ** the function of the code. Important information to put here ** includes the parameters of the routines, any options that the ** user may specify, etc. ** ** The first line of the comment should be a one-line description ** of what's going on. The remainder should be more detailed. ** Blank lines should seperate major points in the comments. In ** general, ask yourself the question, "If I didn't know what this ** code was, what it was for, how it fit in, etc., and if I didn't ** even have the documentation for it, would these comments be ** enough for me?" ** ** Some general guidelines for the code: ** ** ***** GENERAL SYNTAX ***** ** ** - Commas and semicolons should always be followed by a space. ** Binary operators should be surrounded on both sides by ** spaces. Unary operators should be in direct contact ** with the object that they act on, except for "sizeof", ** which should be seperated by one space. ** ** - Two statements should never go on the same line. This includes ** such things as an if and the associated conditionally ** executed statement. ** In cases such as this, the second half of the if ** should be indented one tab stop more than the if. For ** example, use: ** if (cond) ** statement; ** never: ** if (cond) statement; ** or: ** if (cond) ** statement; ** ** - Braces ({}) should (almost) always be on a line by them- ** selves. Exceptions are closing a do, and terminating ** a struct definition or variable initialization. Braces ** should start at the same indent as the statement with ** which they bind, and code inside the braces should be ** indented one stop further. For example, use: ** while (cond) ** { ** code ** } ** and never: ** while (cond) ** { ** code ** } ** or: ** while (cond) { ** code ** } ** or: ** while (cond) ** { ** code ** } ** or anything else in that line. Braces which match ** should always be at the same tab stop. ** ** - Do statements must always be of the form: ** do ** { ** code; ** } while (cond); ** even if "code" is only one line. This is done so that ** it is clear that the "while" is with a do, rather than ** a standalone "while" which is used for the side effects of ** evaluation of the condition. ** ** - There should always be a space following a keyword (i.e., ** for, if, do, while, switch, and return), but never ** between a function and the paren preceeding its ** arguments. For example, use: ** if (i == 0) ** exit(); ** never: ** if(i == 0) ** exit (); ** ** - Every case in a switch statement (including default) should ** be preceeded by a blank line. The actual word "case" or ** "default" should have the indent of the switch statement plus ** two spaces. It should be followed by a space (not a ** tab) and the case constant. Multiple case labels on ** a single block of code should be on seperate lines, but ** they should not be seperated by blank lines. The ** switch statement should in general be used in place of ** such constructs as: if (i == 1) ** code1; ** else if (i == 34) ** code2; ** else if (i == -1643) ** code3; ** which can be more succinctly stated as: ** switch (i) ** { ** case 1: ** code1; ** break; ** ** case 34: ** code2; ** break; ** ** case -1643: ** code3; ** break; ** } ** In point of fact the equivalent switch will compile ** extremely efficiently. (Note that if you had some ** instance where you could not use a case, e.g., checking ** for i < 5, else check for j > 3, else whatever, then ** the above ("if") code is in the correct style. However, ** if (i < 5) ** code1; ** else ** if (j > 3) ** code2; ** else ** code3; ** is acceptable. ** ** - A blank line should seperate the declarations and the code ** in a procedure. Blank lines should also be used freely ** between major subsections of your code. The major ** subsections should also have a block comment giving ** some idea of what is about to occur. ** ** ***** PREPROCESSOR USAGE ***** ** ** - Fields of #defines and #includes should line up. Use: ** # define ARPA 25 ** # define MAXFIELDS 18 ** and not: ** #define ARPA 25 ** #define MAXFIELDS 18 ** Conditional compilation (#ifdef/#endif) should be used ** around all trace information, timing code, and code ** which may vary from version to version of UNIX. See ** the code below for an example of conditional compila- ** tion use. ** ** ***** VARIABLES AND DECLARATIONS ***** ** ** - Defined constants (defined with the # define feature) must ** be entirely upper case. The exceptions to this are ** compilation flags, which begin with a lower case "x", ** and some sub-types for parser symbols. In any case, ** the majority of the symbol is upper case. ** ** - Global variables should begin with an upper case letter and ** be otherwise all lower case. Local symbols should be ** entirely lower case. Procedure names are all lower ** case. The only exception to this is the trace routine ** "tTf". You should avoid user non-local symbols (globals ** or # define'd symbols) which are one character only; ** it is impossible to distinguish them. Capitalization ** may be used freely inside global names so long as they ** are primarily lower case; for example, "ProcName" is ** an acceptable name (and preferred over either Proc_name ** or Procname). ** ** - Use descriptive variable names, particularly for global var- ** iables. "IEH3462" tells me nothing; nor does "R". On ** the other hand, "Resultid" tells me quite a lot, ** including what it might be, where I might go to see ** how it is initialized, etc. Try not to use variables ** for multiple purposes. Variable names like "i" are ** acceptable for loop indices & temporary storage ** provided that the value does not have long-term ** semantic value. ** ** - When the storage structure or type of a variable is ** important, always state it explicitly. In particular, ** include "auto" if you are going to take the address ** of something using the ampersand operator (so that ** some wayward programmer doesn't change it to register), ** and declare int parameters as int instead of letting ** them default. ** ** ***** GENERAL COMMENTS ***** ** ** - It is quite possible to name a file "printr.c" and then ** put the code for "destroydb" in it. Try to arrange ** the names of your files so that given the name of a ** routine, it is fairly easy to figure out which file ** it is in. ** ** - Sometimes it is really pretty much impossible to avoid doing ** something tricky. In these cases, put in a comment ** telling what you are doing and why you are doing it. ** - Try to write things that are clear and safe, rather than ** things which you think are easier to compile. For ** example, always declare temporary buffers as local, ** rather than as global. This way you can another ** routine accidently when it still had useful info ** in it. ** ** ***** COMMENTS ***** ** ** - The importance of comments cannot be overemphasised. ** INGRES is primarily a research vehicle rather than ** a program product. This means that there will be ** many people pouring over your code, trying to ** understand what you have done & modify it to do ** other things. Try to make life easy for them & ** maybe they will be nice to you someday. ** ** - Try to keep an idea of the flow of your program. Put ** block comments at the beginning of major segments, ** and use one-line comments at less major junctures. ** A person viewing your code at ten paces should be ** able to tell where the major segments lay. ** ** - The preferred format for block comments is to begin with ** a line containing slash-star alone, followed by a ** number of lines all beginning star-star containing ** the comment, and terminating with a line containing ** star-slash alone. Comments without the double-star ** at the beginning of each line should be avoided, ** since it makes the comments seemingly disappear into ** the body of the code. ** ** - The beginning of each routine should have a comment block ** in parametric form as demonstrated below. The fields ** "Parameters", "Returns", and "Side Effects" should ** be considered mandatory. Mark parameters as being ** (IN), (IN/OUT), or (OUT) parameters, depending on ** whether the parameter is used only to transmit infor- ** mation into the routine, in and out of the routine, ** or only to return information; the default is (IN). ** ** Remember, it is easy to write totally incomprehensible code in ** C, but we don't go in for that sort of thing. It isn't too ** much harder to write brilliantly clear code, and the code is ** worth a lot more later. ** ** For efficiency reasons, you should always use register variables ** when possible. A simple and extremely effective tip is to define ** a register variable, and assign an oft-used parameter to it, ** since it is particularly inefficient to reference a parameter. ** Another particularly inefficient operation is referencing arrays ** of structures. When possible, define a register pointer to the ** structure, and then say: ** struct xyz structure[MAX]; ** register struct xyz *p; ** ... ** for (i = 0; i < MAX; i++) ** { ** p = &structure[i]; ** p->x = p->y + p->z; ** (diddle with p->???) ** } ** and not: ** struct xyz structure[MAX]; ** ... ** for (i = 0; i < MAX; i++) ** { ** Structure[i].x = Structure[i].y + Structure[i].z; ** (diddle with Structure[i].???) ** } ** Remember, the nice things about register variables is that they ** make your code smaller and they run faster. It is hard to ** lose with registers. There are three restrictions which you ** should be aware of on register variables, however. First, ** The only types which may be registers are int's, char's, ** and pointers. Second, there may only be three register ** variables per subroutine. Third, you may not take the address ** of a register variable (i.e., you may not say "&i" if i is ** typed as a register variable). ** ** Usage: ** example [flags] argument ** ** Positional Parameters: ** argument -- this gets echoed to the standard ** output. ** ** Flags: ** -n -- don't put a newline at the end. ** -x -- don't do anything. ** -b -- echo it with a bell character. ** ** Return Codes: ** 0 -- successful ** else -- failure ** ** Defined Constants: ** XEQ1 -- maximum number of simultaneous equijoins. ** ** Compilation Flags: ** xTRACE -- enable trace information ** ** Trace Flags: ** 5 -- general debug ** 6 -- reserved for future use ** Compilation Instructions: ** cc -n example.c ** mv a.out example ** chmod 755 example ** ** Notes: ** These comments don't apply to the code at all, ** since this is just an example program. ** Also, it is wise to avoid this many comments ** except at the head of main programs and ** at the head of major modules. For example, ** this sort of commenting is appropriate at ** the top of ingres.c (system startup) and ** view.c (virtual view subsystem), but not ** in small utility routines, e.g., length.c. ** This sort of routine should be limited to ** "Parameters:", "Returns:", "Side Effects:", ** and anything else that seems relevant in ** that context. ** A fairly large comment block should exist at the ** top of modules [files] which contain many ** procedures; this block should clarify why ** the procedures are grouped together, that ** is, their common purpose in life. A small ** block should occur at the top of each ** procedure explaining details of that proce- ** dure. ** Procedures should be on seperate pages (use the ** form feed character, control-L). ** A program will help you generate this comment block. ** In ex, go to the line where you want to insert ** a block and say "so /mnt/ingres/comment". It ** will ask you for a block type, e.g., "main" ** for main program, "modfn" for a file which ** contains only one function, "function" or ** "procedure" for a procedure within a module, ** "module" for a module header (e.g., as a ** seperate comment block for a major module ** [check .../qrymod/view.c for an example] or ** in header files. ** SCCS should be considered an essential tool, if only ** to maintain history fields. ** ** Deficiencies: ** It should handle pseudo tty's. */ /* the following macro is defined by <sccs.h> */ SCCSID(%W%); /* %W% is replaced by a version number by SCCS */ # define XEQ1 5 struct magic { char *name; /* name of symbol */ int type; /* type of symbol, defined in symbol.h */ int value; /* optional value. This is actually * the value if it is type "integer", * a pointer to the value if it is a * string. */ }; struct magic Stuff; main(argc, argv) int argc; char *argv[]; { register struct magic *r; register int i; register int j; int timebuf[2]; auto int status; /* ** Note that in the declarations of argc and argv above, all ** parameters to any function should be declared, even if they ** are of type int (which is the default). */ r = &Stuff; /* initialize random # generator */ time(timebuf); srand(timebuf[1]); /* scan Stuff structure */ for (i = 0; i < XEQ1; i++) { # ifdef xTRACE if (tTf(5, 13)) printf("switch on type %d\n", r->reltype); # endif switch (r->type) { case 0: case 1: case 3: /* initialize */ printf("hi\n"); break; case 2: /* end of query */ printf("bye\n"); break; default: /* ** be sure to print plenty of info on an error; ** "syserr("bad reltype");" would not have been ** sufficient. However, don't make syserr's ** overly verbose; they take much space in the ** object module, and it will probably be ** necessary to look at the code anyway. */ syserr("main: bad type %d", r->type); } } /* resist the temptation to say "} else {" */ if (i == 5) { i++; j = 4; } else i--; /* plot the results */ do { i = rand() & 017; plot(i); } while (j--); /* wait for child processes to complete */ wait(&status); /* end of run, print termination message and exit */ for (i = 0; i < 2; i++) printf("bye "); printf("\n"); } ** PLOT -- Plot a Bar-Graph ** ** Does a simple plot on a terminal -- one line's worth. ** ** Parameters: ** n (IN) -- number of asterisks to plot ** ** Returns: ** none ** ** Side Effects: ** none ** ** Deficiencies: ** Should allow scaling. */ plot(n) int n; { register int i; for (i = n; i-- > 0; ) { printf("*"); } printf("\n"); } ************************************************************************** BBN PROGRAMMING STANDARDS FOR C The following document was provided by Dan Franklin <DAN at BBN=UNIX> in response to a general enquiry distributed to Arpanet BBOARDS: Here's a short set of guidelines that represents a combination of the thoughts of two groups within BBN. I was its last editor. Hope you find it useful. If you come across something more comprehensive (which this certainly isn't), I'd appreciate it if you let me know. PROGRAMMING STANDARDS AND PRACTICES FOR THE UNIX COST CENTER This memo proposes a set of practices that might be followed in the cost center, in order to have a consistently organized and written, readable, understandable, and ultimately maintainable software package. Qualifying each of the items below is an (S) or (P): the former indicates that, once agreed-upon, the rule must be adhered to rigorously and consistently--a Standard; the latter items are more of the flavour of "good programming Practice"--once agreed-upon, programmers should follow the practice to the extent that common sense dictates. 1. DOCUMENTATION OF ROUTINE INTERFACES (S) Every routine should be prefaced by a standard header which describes the routine and its interface precisely, so that the routine could be used by someone without reading the code. The rationale for such a header is that it concentrates the critical document- ation in one place, making it easy for someone (including the original designer/coder) to use the routine correctly, and allows for the possibility of automatically stripping off all headers to form an Internal Documentation document. In some cases a routine may do a small amount of processing and then call another routine. (As an example, a routine may provide a "special case" interface to another more general routine with a more cumbersome calling sequence.) In this case, a routine's header may refer the reader to the header of another routine for further information. The format suggested is illustrated below: comments are surrounded by < > symbols. Any item that is irrelevant, e.g., no parameters, no return value, no error conditions, may be omitted. /*------------------------ E P R I N T -----------------------------------*/ /* <a brief description of the routine...also, put the routine name in * caps in the line above. The description should give, in general * terms, the routine's function, including an overall description of its * parameters, return values, and effect on global databases. It should also * describe any error conditions that may occur and be reflected to the * caller. The return value must be described precisely.> */ int eprint(estrucp, istart, ilength) struct estruct *estructp; /* Pointer to eprint's structure */ int istart; /* Place in structure to start from */ int ilength; /* # things in struct to print */ { } Note that each parameter gets its own declaration line, and has a comment to convey its exact meaning. Each file in a program or subsystem consisting of multiple files should start with some additional information, giving (essentially) the justification for putting all these routines in one file. That is, it should include a description of the common function they all perform, the related functions they all perform, the database they have in common and which is contained only in this file, etc. In the last case, especially, a detailed description of the database should be included; otherwise, since the database is not part of any one routine, it will not get described in any other comment field. The detailed description may require reading comments associated with the actual declarations in order to be complete. This header should include a history list describing all modifications to functions in this file. Each entry in the list should give the person, the date, the names of the functions (or database elements) changed, and the reasons. For the file containing the main routine of a program, the following standards should be observed: 1. The main routine should be the first routine in the file. 2. Before the main routine should appear an overall comment field describing the calling sequence in some detail. Generally, the program will also be described in a manual page as well; this comment field need not duplicate the entire contents of the manual page, but it should include information about the overall structure of the program which would be useful to a maintainer. 3. The main routine should exit by calling exit(0) explicitly. All programs, however, must return an exit status of zero on success, and nonzero on error. 2. FORMATTING (S) All programs must be indented, at least 4 spaces per indentation level. Statements at the same nesting level should be at the same indentation level; statements at deeper nesting levels should be indented more. (For the purposes of this standard, the keyword "else" is regarded as having the same nesting level as the "if" it corresponds to.) For example, the following indentation practices are not permitted: if (condition) statement-group; if (condition) statement-group; else statement-group; if (condition) for (init; test; step) statement-group; if (condition) statement-group; else statement group; (S) Nesting the trinary conditional operator (?:) is not permitted. (P) For internal formatting and indenting style, the following is recommended: . 4-space indentations at each level; . braces delineating blocks used in the style of if (exp) { code } or if (exp) { code } . a separate declaration statement for each pointer, due to the confusion that can arise when reading and modifying a declaration like char *a, b, *c; . comments lined up systematically; . spaces between reserved words and their opening parentheses, e.g., if (condition) rather than if(condition); . no deep nesting (greater than 4 levels deep) . statement blocks less than 1 page long . one statement per line . parentheses around the objects of sizeof and return. (P) Concerning internal comments: . Full English sentences are recommended. . It is often clearer and more readable to make small blocks of comments as "paragraph headers" to a block of code than to comment every line or so, especially if the code is straightforward and untricky (which most of it should be, especially if the programmer is conscientious about variable naming and datatype compatibility). . Anything non-obvious should be well-commented. (P) Concerning white space and other aids to readability and debugging: . blank lines should be used between blocks of code that are functionally distinct . in expressions, operators should be surrounded by blanks (but not operators which compose primaries, specifically ".", "->") . in a function definition, the function name and its datatype should appear on one line. Examples: int pread(...) SOMESTRUCT * function(param1, param2) This latter practice aids readability and the comparison of the definition of a routine with its uses. (P) Other suggestions for improving readability: . Side effects within expressions should be used sparingly. It is recommended that no more than one operator with a side effect (=, op=, ++, --) appear within an expression. Function calls with side effects count as operators for this purpose. . In an "if-else" chain, the form if (condition) statement; else if (condition) statement; else if (condition) statement; should only be used when the conditions are all of the same basic form: e.g., testing the same variable against different values. If the conditions are qualitatively different, the additional "if" statements should start on new lines, indented, as in if (cond) statement; else if (cond2) statement; else statement; . In the condition portion of an if, for, while, etc., side effects whose effect extends beyond the extent of the guarded statement block should be minimized. That is, in a block like if ((c = getc(file)) != EOF) { guarded-stmts } other-stmts it is natural to think of "c" being "bound" to a value only within the guarded-stmts; use of a variable set or modified in a condition, outside the range of the statements guarded by the condition, is quite distracting. . The use of || and && with right hand operands having side effects is discouraged. Also, whenever || and && are mixed in the same expression, parentheses should be used for clarity. 3. MODULARITY 3.1. Routine Length (P) Routines should be kept reasonably short. In general, a routine (or command) processes one or more inputs and generates one or more outputs, where each of the inputs and outputs can be concisely described. Usually a routine should only perform one function. Signs that a routine is too long, and ought to be split up, are: length greater than two pages; heavy use of "internal" variables (variables whose scope is less than the entire routine). 3.2. Shared Data and Include Files (S) Declarations of variables that are to be shared among several routines in a package should be placed at the beginning of the file containing the routines. If they are entirely internal to the package, they should be declared "static" to hide them from other files. (S) Declarations of structures and global variables used for communications between a package and its callers should be placed in an appropriately named .h file. Shared global variables should be declared extern in the .h file so that if the package which sets/uses them is accidentally not loaded, a diagnostic will be issued by the loader. (S) Definition and optional initialization of such globals should reside in one and only one file for each program. If a global is clearly associated with a specific package, it may be defined in the file for that package; otherwise, it should be placed in a file called data.c which is compiled and linked with the other routines when a program is being built. (P) Use of globals should be minimized by judicious use of parameters. Note that while static and extern designators in C both yield "common" storage allocation, static allows the named variable to be known only within the context in which it is declared; thus, an identifier declared static at the top of a file will only be known within the file. In addition, local symbolic constants (#defines) may occur anywhere within a routine, and may be placed below the #include directives if the writer feels that this aids readability. (S) Include files should contain all and only all of the following items necessary for a given program and shared among two or more of its files: . #defines . typedefs . extern declarations (S) Include files may also contain nested #include directives. However, this practice should be kept to a minimum. It is recommended that include files which may be embedded in this way contain a check to see whether they are being included twice, to avoid unnecessary preprocessor and compiler complaints when the user includes them both implicitly and explicitly. The simplest way to do this is to check for a special hidden #define, as in #ifdef _INCLUDEFILENAME #define _INCLUDEFILENAME . . Contents of include file . #endif _INCLUDEFILENAME 3.3 Routine interfaces (P) In general, a routine should be designed with a "natural", easily-remembered calling sequence. Routines with more than five arguments are not recommended. Routines with "op-code" arguments, where one argument determines the interpretation and functions of the others, are also not recommended (though they may prove useful as internal routines to a package, they should NOT be part of a package's documented interface). 4. PORTABILITY (P) Adherence to datatype compatibility should be practiced where reasonable. This can be facilitated by liberal use of C's typedef facility and explicit casting of types, as well as by the use of the union datatype. (P) The following violation of strict adherence is permitted: a package which returns a pointer to a structure whose format need not be known outside that package may return a "generic" pointer, of type (char *). It is recommended that the typedef PTR be used for this purpose; this typedef will be provided in some standard system file. Note that char* is specifically chosen because the language guarantees that any pointer may be converted to a char* and back again without harm. (S) Liberal use of #defines should eliminate "magic numbers", whether machine dependent or implementation dependent or arbitrary/random. (S) To the extent that the conditional compilation facility of C allows, non- portable constructions can use this facility. Failing this, machine or implementation dependent constructs should be visibly commented in the code. When using conditional compilation for portability purposes, be sure to use appropriate parameters, rather than machine type, wherever possible. For example, code which handles the C machine's 20 bit wordsize or 10 bit bytesize should use the parameter BYTESIZE in cpu.h rather than being ifdeffed on "mbb". (P) Up to six register variables can be declared (with some effect) on the C70 machine, but only three on the 11/70 (where additional ones are assigned regular automatic storage). Therefore, the first three register variables declared (in lexicographic order) should be ones for which the most gain can be gotten. Note that register variables, judiciously chosen, can be very good space/time savers, but the compiler is not overly smart about them, and can give you irritating "expression overflow" messages. In general, as with any "optimization", it is wise to design, code and debug first, and then add in register storage to one's declarations. 5. NAMING (P) Names should be chosen for their mnemonic nature. Recall that although there is a limit on the number of initial characters of a name that must be distinct in C (and for a given machine), this does not prevent any name from being longer if such length will aid readability. (S) It is a useful C convention to use upper-case for #defines and typedef names. (S) One exception to the above is for parameterized #defines. These may be in lower-case. ************************************************************************** The following was provided via FTP by Keith A. Lantz at Stanford <CSL.LANTZ at SU-SCORE> via FTP following the enquiry distributed via Arpanet BBOARDS. 1 NETWORK GRAPHICS C STYLE SHEET Andrew Shore, et al. Computer Systems Laboratory Stanford University Stanford, CA 94305 18 June 1982 1. Names Don't use capital letters in file names (except for V !?). Avoid the underscore. Global variables, procedures, structs, unions, typedefs, defined constants, and macros all begin with a capital letter, and are logically capitalized thereafter (e.g. MainHashTable). A global variable is one defined outside a procedure, even though it may not be exported from the file, or an external variable. The motivation for treating macros and constants this way is that they may then be freely changed to procedure calls or (global or external) variables. Local variables begin with a lower-case letter, but are logically capitalized thereafter (e.g. bltWidth, power, maxSumOfSquares). Fields within structures or unions are treated in this manner also. 2. Comments There are generally two types of comments: block-style comments, and on-the- line comments. Multi-line, block-style comments will follow the UNIX style of /* and */ appearing on lines by themselves, and the body of the comment will start with a properly aligned *. The comment should usually be surrounded by blank lines as well. The motivation for this is that it is easy to add/delete first and last lines, and it is easier to detect the common error of omitting the */ and thus including all code up to and including the next */ in a comment (Yapp helps with that too). /* * this is the first line of a multi-line comment, * this is another line * the last line of text */ On-line comments are used to detail declarations, and to explain single lines of code. And, I suppose, for brief (i.e. one line) block-style descriptive comments. 1 This work was supported by the Defense Advanced Research Projects Agency under contract number MDA903-80-C-0102. 2 Procedures are preceded by block-style comments, explaining their (abstract) function in terms of their parameters, results, and side effects. Note that the parameter declarations are indented, not flushed left. /* * Unblock: * unblock the process pd */ Unblock( pd ) register Process pd; /* the process to unblock */ { register Process *currPd, *tmpPd; register unsigned prio; prio = pd->priority; Disable; pd->state = Ready; /* Add pd to the ready queue */ currPd = (Process *) &ReadyqHead; while ((tmpPd = currPd->link) != Null) { if (tmpPd->priority > prio) break; currPd = tmpPd; } pd->link = tempPd; currPd->link = pd; Enable; } 3. Indenting The above example shows many of the indenting rules. Braces ( "{" and "}" ) appear alone on a line, and are indented two spaces from the statement they are to contain the body of, the body is indented two more spaces from the braces (for a total of four spaces). else's and else if's line up with their dominating if statement (to avoid marching off to the right, and to reflect the semantics of the statement). 3 if ((x = y) == 0) { flag = 1; printf (" the value was zero "); } else if (y == 1) { switch (today) { case Thursday: flag = 2; ThursdayAction(); break; case Friday: flag = 3; FridayAction(); break; default: OtherDayAction(); } } else printf(" y had the wrong value "); 4. File Contents I think we agreed on the following order for file contents. 1. initial descriptive comment (see example below) which contains: a. file name, with indication of the relative path to it when relevant b. brief descriptive abstract of contents c. a list of all defined procedures in their defined order d. list of authors e. list of current maintainers f. list of recent and major modifications in reverse chronological order with indication (initials) of who made the change. 2. included files (use relative path names whenever possible) 3. external definitions (imports and exports) 4. function declarations (externals and forward references) 4 5. constant declarations 6. macro definitions 7. type definitions 8. global variable declarations 9. procedure and function definitions Here is an example of the header comment: /* * FILE: libc/vkstuff/malloc.c * * CONTENTS: * C storage allocator stolen and hacked up from UNIX for the SUN * (NOTE: these were stolen and have the wrong naming conventions) * malloc * free * realloc * allock DEBUG ONLY! * SetBrk ! our routine to fake up sbrk() * * AUTHORS: stolen and hacked by Andrew I. Shore (shore) * * MAINTAINER: shore * * HISTORY: * 03/05/82 AIS replaced calls to UNIX sbrk() with calls to own version * SetBrk() for the sun/Vkernel */ 5. Parenthesis () We seem to have decided on the following conventions for parentheses. When parentheses enclose the expression for a statement (if, for, etc.), the parentheses `belong to' the expression, so there is a space between the keyword and the parenthesized expression. For function calls the parentheses `belong to' the call, so there is no space between function name and open paren (there may some inside the parentheses to make the expression list (argument list) look nice). if (Mumble()) { Grumble( (a = b) == 0 ); return (Nil); } else { Fumble( a, b, c ); return (ToSender); } 5 It is unclear what to do with return. Note, then, that it is operators that cause spaces on the outside of parentheses -- (a + b) * c. 6. General 1. One statement/declaration per line. 2. Make judicious use of blank lines. a. At least 3 blank lines between individual procedures. b. Blank lines surround "large" comments. 3. Make sure comments and code agree! 4. Don't just echo the code with comments -- make every comment count! i.e. nix on: /* add foo to bar */ bar += foo; i Table of Contents 1. Names 1 2. Comments 1 3. Indenting 2 4. File Contents 3 5. Parenthesis () 4 6. General 5 ************************************************************************** ------- Date: 27 Jun 1982 11:48:50-PDT From: mo at LBL-UNIX (Mike O'Dell [system]) To: JSol at USC-ECLC cc: Header-People at MIT-MC Subject: Re: Unexplored Topic -- Length of Mail Message In-reply-to: Your message of 25 Jun 1982 1715-PDT (Friday). Yes indeed mail can be BIG!! If you don't have FTP to some random system (again, not ARPAnet, most likely), but DO have mail, you do a LOT with it, like abuse it into make-do FTP. It is crass, but it beats not getting the bits there! This can often be the case with site 2 networks away in the internet (note small "i"). While this shouldn't impact ARPAnet sites too much, if 733 is indeed something the larger world might look to for guidance, I would advocate JSol's position: Mail is another form of machine-machine communications, complete unto itself. As an example, the "net.sources" news topic on USENET routinely posts fixes and entire source listings of quite complex programs; and this is on a network with 300 or 1200 baud hop-by-hop links!! I am not saying this is the ulitimate solution, or that we should advocate such things, but it does indicate the tremendous utility of Mail in reducing the isolation of sites. -Mike Date: 27 Jun 1982 0929-PDT From: JBROOKSHIRE at USC-ECLB Subject: Re: C programming standards To: mp at MIT-MC In response to your message sent Saturday, 26 June 1982, 23:56-EDT Thanks for the note - if you have any pointers it might help. I have received three pretty good sets of stuff that I am enclosing here if you are interested. They are separated by lines of ******** which you can search on if you just want to read the sources of each. Regards, Jerry Brookshire INGRES CODING CONVENTIONS FOR C/UNIX PROGRAMMING University of California, Berkeley "The Ingres data base system encompasses about 75,000 lines of code in the programming language `C' and runs on top of the Unix operating system. Over the past six years, Ingres has evolved into a functionally complete and usable prototype. Development required 25 to 30 programmer-years by a total of 19 people, and the systems is now in use at over 125 sites around the world." Allman, Eric.; and Stonebreaker, Michael "Observations on the Evolution of a Software System." COMPUTER 15, 6 (June 1982), 27-32. The following represents the current C coding conventions that have evolved from and during the development of the Ingres system. This document has been provided by Joe Kalash of Berkeley <INGVAX.kalash at Berkeley> in response to a general enquiry distributed via Arpanet BBOARDS. /* ** CODE_CNVNTNS.C -- A Program to Display the INGRES Coding Style ** ** This hunk of code does virtually nothing of use. Its main ** purpose is to demonstrate the "official" ingres coding style. ** ** This demonstrates comments. There should be a block comment ** at the beginning of every file and/or procedure to explain ** the function of the code. Important information to put here ** includes the parameters of the routines, any options that the ** user may specify, etc. ** ** The first line of the comment should be a one-line description ** of what's going on. The remainder should be more detailed. ** Blank lines should seperate major points in the comments. In ** general, ask yourself the question, "If I didn't know what this ** code was, what it was for, how it fit in, etc., and if I didn't ** even have the documentation for it, would these comments be ** enough for me?" ** ** Some general guidelines for the code: ** ** ***** GENERAL SYNTAX ***** ** ** - Commas and semicolons should always be followed by a space. ** Binary operators should be surrounded on both sides by ** spaces. Unary operators should be in direct contact ** with the object that they act on, except for "sizeof", ** which should be seperated by one space. ** ** - Two statements should never go on the same line. This includes ** such things as an if and the associated conditionally ** executed statement. ** In cases such as this, the second half of the if ** should be indented one tab stop more than the if. For ** example, use: ** if (cond) ** statement; ** never: ** if (cond) statement; ** or: ** if (cond) ** statement; ** ** - Braces ({}) should (almost) always be on a line by them- ** selves. Exceptions are closing a do, and terminating ** a struct definition or variable initialization. Braces ** should start at the same indent as the statement with ** which they bind, and code inside the braces should be ** indented one stop further. For example, use: ** while (cond) ** { ** code ** } ** and never: ** while (cond) ** { ** code ** } ** or: ** while (cond) { ** code ** } ** or: ** while (cond) ** { ** code ** } ** or anything else in that line. Braces which match ** should always be at the same tab stop. ** ** - Do statements must always be of the form: ** do ** { ** code; ** } while (cond); ** even if "code" is only one line. This is done so that ** it is clear that the "while" is with a do, rather than ** a standalone "while" which is used for the side effects of ** evaluation of the condition. ** ** - There should always be a space following a keyword (i.e., ** for, if, do, while, switch, and return), but never ** between a function and the paren preceeding its ** arguments. For example, use: ** if (i == 0) ** exit(); ** never: ** if(i == 0) ** exit (); ** ** - Every case in a switch statement (including default) should ** be preceeded by a blank line. The actual word "case" or ** "default" should have the indent of the switch statement plus ** two spaces. It should be followed by a space (not a ** tab) and the case constant. Multiple case labels on ** a single block of code should be on seperate lines, but ** they should not be seperated by blank lines. The ** switch statement should in general be used in place of ** such constructs as: if (i == 1) ** code1; ** else if (i == 34) ** code2; ** else if (i == -1643) ** code3; ** which can be more succinctly stated as: ** switch (i) ** { ** case 1: ** code1; ** break; ** ** case 34: ** code2; ** break; ** ** case -1643: ** code3; ** break; ** } ** In point of fact the equivalent switch will compile ** extremely efficiently. (Note that if you had some ** instance where you could not use a case, e.g., checking ** for i < 5, else check for j > 3, else whatever, then ** the above ("if") code is in the correct style. However, ** if (i < 5) ** code1; ** else ** if (j > 3) ** code2; ** else ** code3; ** is acceptable. ** ** - A blank line should seperate the declarations and the code ** in a procedure. Blank lines should also be used freely ** between major subsections of your code. The major ** subsections should also have a block comment giving ** some idea of what is about to occur. ** ** ***** PREPROCESSOR USAGE ***** ** ** - Fields of #defines and #includes should line up. Use: ** # define ARPA 25 ** # define MAXFIELDS 18 ** and not: ** #define ARPA 25 ** #define MAXFIELDS 18 ** Conditional compilation (#ifdef/#endif) should be used ** around all trace information, timing code, and code ** which may vary from version to version of UNIX. See ** the code below for an example of conditional compila- ** tion use. ** ** ***** VARIABLES AND DECLARATIONS ***** ** ** - Defined constants (defined with the # define feature) must ** be entirely upper case. The exceptions to this are ** compilation flags, which begin with a lower case "x", ** and some sub-types for parser symbols. In any case, ** the majority of the symbol is upper case. ** ** - Global variables should begin with an upper case letter and ** be otherwise all lower case. Local symbols should be ** entirely lower case. Procedure names are all lower ** case. The only exception to this is the trace routine ** "tTf". You should avoid user non-local symbols (globals ** or # define'd symbols) which are one character only; ** it is impossible to distinguish them. Capitalization ** may be used freely inside global names so long as they ** are primarily lower case; for example, "ProcName" is ** an acceptable name (and preferred over either Proc_name ** or Procname). ** ** - Use descriptive variable names, particularly for global var- ** iables. "IEH3462" tells me nothing; nor does "R". On ** the other hand, "Resultid" tells me quite a lot, ** including what it might be, where I might go to see ** how it is initialized, etc. Try not to use variables ** for multiple purposes. Variable names like "i" are ** acceptable for loop indices & temporary storage ** provided that the value does not have long-term ** semantic value. ** ** - When the storage structure or type of a variable is ** important, always state it explicitly. In particular, ** include "auto" if you are going to take the address ** of something using the ampersand operator (so that ** some wayward programmer doesn't change it to register), ** and declare int parameters as int instead of letting ** them default. ** ** ***** GENERAL COMMENTS ***** ** ** - It is quite possible to name a file "printr.c" and then ** put the code for "destroydb" in it. Try to arrange ** the names of your files so that given the name of a ** routine, it is fairly easy to figure out which file ** it is in. ** ** - Sometimes it is really pretty much impossible to avoid doing ** something tricky. In these cases, put in a comment ** telling what you are doing and why you are doing it. ** - Try to write things that are clear and safe, rather than ** things which you think are easier to compile. For ** example, always declare temporary buffers as local, ** rather than as global. This way you can another ** routine accidently when it still had useful info ** in it. ** ** ***** COMMENTS ***** ** ** - The importance of comments cannot be overemphasised. ** INGRES is primarily a research vehicle rather than ** a program product. This means that there will be ** many people pouring over your code, trying to ** understand what you have done & modify it to do ** other things. Try to make life easy for them & ** maybe they will be nice to you someday. ** ** - Try to keep an idea of the flow of your program. Put ** block comments at the beginning of major segments, ** and use one-line comments at less major junctures. ** A person viewing your code at ten paces should be ** able to tell where the major segments lay. ** ** - The preferred format for block comments is to begin with ** a line containing slash-star alone, followed by a ** number of lines all beginning star-star containing ** the comment, and terminating with a line containing ** star-slash alone. Comments without the double-star ** at the beginning of each line should be avoided, ** since it makes the comments seemingly disappear into ** the body of the code. ** ** - The beginning of each routine should have a comment block ** in parametric form as demonstrated below. The fields ** "Parameters", "Returns", and "Side Effects" should ** be considered mandatory. Mark parameters as being ** (IN), (IN/OUT), or (OUT) parameters, depending on ** whether the parameter is used only to transmit infor- ** mation into the routine, in and out of the routine, ** or only to return information; the default is (IN). ** ** Remember, it is easy to write totally incomprehensible code in ** C, but we don't go in for that sort of thing. It isn't too ** much harder to write brilliantly clear code, and the code is ** worth a lot more later. ** ** For efficiency reasons, you should always use register variables ** when possible. A simple and extremely effective tip is to define ** a register variable, and assign an oft-used parameter to it, ** since it is particularly inefficient to reference a parameter. ** Another particularly inefficient operation is referencing arrays ** of structures. When possible, define a register pointer to the ** structure, and then say: ** struct xyz structure[MAX]; ** register struct xyz *p; ** ... ** for (i = 0; i < MAX; i++) ** { ** p = &structure[i]; ** p->x = p->y + p->z; ** (diddle with p->???) ** } ** and not: ** struct xyz structure[MAX]; ** ... ** for (i = 0; i < MAX; i++) ** { ** Structure[i].x = Structure[i].y + Structure[i].z; ** (diddle with Structure[i].???) ** } ** Remember, the nice things about register variables is that they ** make your code smaller and they run faster. It is hard to ** lose with registers. There are three restrictions which you ** should be aware of on register variables, however. First, ** The only types which may be registers are int's, char's, ** and pointers. Second, there may only be three register ** variables per subroutine. Third, you may not take the address ** of a register variable (i.e., you may not say "&i" if i is ** typed as a register variable). ** ** Usage: ** example [flags] argument ** ** Positional Parameters: ** argument -- this gets echoed to the standard ** output. ** ** Flags: ** -n -- don't put a newline at the end. ** -x -- don't do anything. ** -b -- echo it with a bell character. ** ** Return Codes: ** 0 -- successful ** else -- failure ** ** Defined Constants: ** XEQ1 -- maximum number of simultaneous equijoins. ** ** Compilation Flags: ** xTRACE -- enable trace information ** ** Trace Flags: ** 5 -- general debug ** 6 -- reserved for future use ** Compilation Instructions: ** cc -n example.c ** mv a.out example ** chmod 755 example ** ** Notes: ** These comments don't apply to the code at all, ** since this is just an example program. ** Also, it is wise to avoid this many comments ** except at the head of main programs and ** at the head of major modules. For example, ** this sort of commenting is appropriate at ** the top of ingres.c (system startup) and ** view.c (virtual view subsystem), but not ** in small utility routines, e.g., length.c. ** This sort of routine should be limited to ** "Parameters:", "Returns:", "Side Effects:", ** and anything else that seems relevant in ** that context. ** A fairly large comment block should exist at the ** top of modules [files] which contain many ** procedures; this block should clarify why ** the procedures are grouped together, that ** is, their common purpose in life. A small ** block should occur at the top of each ** procedure explaining details of that proce- ** dure. ** Procedures should be on seperate pages (use the ** form feed character, control-L). ** A program will help you generate this comment block. ** In ex, go to the line where you want to insert ** a block and say "so /mnt/ingres/comment". It ** will ask you for a block type, e.g., "main" ** for main program, "modfn" for a file which ** contains only one function, "function" or ** "procedure" for a procedure within a module, ** "module" for a module header (e.g., as a ** seperate comment block for a major module ** [check .../qrymod/view.c for an example] or ** in header files. ** SCCS should be considered an essential tool, if only ** to maintain history fields. ** ** Deficiencies: ** It should handle pseudo tty's. */ /* the following macro is defined by <sccs.h> */ SCCSID(%W%); /* %W% is replaced by a version number by SCCS */ # define XEQ1 5 struct magic { char *name; /* name of symbol */ int type; /* type of symbol, defined in symbol.h */ int value; /* optional value. This is actually * the value if it is type "integer", * a pointer to the value if it is a * string. */ }; struct magic Stuff; main(argc, argv) int argc; char *argv[]; { register struct magic *r; register int i; register int j; int timebuf[2]; auto int status; /* ** Note that in the declarations of argc and argv above, all ** parameters to any function should be declared, even if they ** are of type int (which is the default). */ r = &Stuff; /* initialize random # generator */ time(timebuf); srand(timebuf[1]); /* scan Stuff structure */ for (i = 0; i < XEQ1; i++) { # ifdef xTRACE if (tTf(5, 13)) printf("switch on type %d\n", r->reltype); # endif switch (r->type) { case 0: case 1: case 3: /* initialize */ printf("hi\n"); break; case 2: /* end of query */ printf("bye\n"); break; default: /* ** be sure to print plenty of info on an error; ** "syserr("bad reltype");" would not have been ** sufficient. However, don't make syserr's ** overly verbose; they take much space in the ** object module, and it will probably be ** necessary to look at the code anyway. */ syserr("main: bad type %d", r->type); } } /* resist the temptation to say "} else {" */ if (i == 5) { i++; j = 4; } else i--; /* plot the results */ do { i = rand() & 017; plot(i); } while (j--); /* wait for child processes to complete */ wait(&status); /* end of run, print termination message and exit */ for (i = 0; i < 2; i++) printf("bye "); printf("\n"); } ** PLOT -- Plot a Bar-Graph ** ** Does a simple plot on a terminal -- one line's worth. ** ** Parameters: ** n (IN) -- number of asterisks to plot ** ** Returns: ** none ** ** Side Effects: ** none ** ** Deficiencies: ** Should allow scaling. */ plot(n) int n; { register int i; for (i = n; i-- > 0; ) { printf("*"); } printf("\n"); } ************************************************************************** BBN PROGRAMMING STANDARDS FOR C The following document was provided by Dan Franklin <DAN at BBN=UNIX> in response to a general enquiry distributed to Arpanet BBOARDS: Here's a short set of guidelines that represents a combination of the thoughts of two groups within BBN. I was its last editor. Hope you find it useful. If you come across something more comprehensive (which this certainly isn't), I'd appreciate it if you let me know. PROGRAMMING STANDARDS AND PRACTICES FOR THE UNIX COST CENTER This memo proposes a set of practices that might be followed in the cost center, in order to have a consistently organized and written, readable, understandable, and ultimately maintainable software package. Qualifying each of the items below is an (S) or (P): the former indicates that, once agreed-upon, the rule must be adhered to rigorously and consistently--a Standard; the latter items are more of the flavour of "good programming Practice"--once agreed-upon, programmers should follow the practice to the extent that common sense dictates. 1. DOCUMENTATION OF ROUTINE INTERFACES (S) Every routine should be prefaced by a standard header which describes the routine and its interface precisely, so that the routine could be used by someone without reading the code. The rationale for such a header is that it concentrates the critical document- ation in one place, making it easy for someone (including the original designer/coder) to use the routine correctly, and allows for the possibility of automatically stripping off all headers to form an Internal Documentation document. In some cases a routine may do a small amount of processing and then call another routine. (As an example, a routine may provide a "special case" interface to another more general routine with a more cumbersome calling sequence.) In this case, a routine's header may refer the reader to the header of another routine for further information. The format suggested is illustrated below: comments are surrounded by < > symbols. Any item that is irrelevant, e.g., no parameters, no return value, no error conditions, may be omitted. /*------------------------ E P R I N T -----------------------------------*/ /* <a brief description of the routine...also, put the routine name in * caps in the line above. The description should give, in general * terms, the routine's function, including an overall description of its * parameters, return values, and effect on global databases. It should also * describe any error conditions that may occur and be reflected to the * caller. The return value must be described precisely.> */ int eprint(estrucp, istart, ilength) struct estruct *estructp; /* Pointer to eprint's structure */ int istart; /* Place in structure to start from */ int ilength; /* # things in struct to print */ { } Note that each parameter gets its own declaration line, and has a comment to convey its exact meaning. Each file in a program or subsystem consisting of multiple files should start with some additional information, giving (essentially) the justification for putting all these routines in one file. That is, it should include a description of the common function they all perform, the related functions they all perform, the database they have in common and which is contained only in this file, etc. In the last case, especially, a detailed description of the database should be included; otherwise, since the database is not part of any one routine, it will not get described in any other comment field. The detailed description may require reading comments associated with the actual declarations in order to be complete. This header should include a history list describing all modifications to functions in this file. Each entry in the list should give the person, the date, the names of the functions (or database elements) changed, and the reasons. For the file containing the main routine of a program, the following standards should be observed: 1. The main routine should be the first routine in the file. 2. Before the main routine should appear an overall comment field describing the calling sequence in some detail. Generally, the program will also be described in a manual page as well; this comment field need not duplicate the entire contents of the manual page, but it should include information about the overall structure of the program which would be useful to a maintainer. 3. The main routine should exit by calling exit(0) explicitly. All programs, however, must return an exit status of zero on success, and nonzero on error. 2. FORMATTING (S) All programs must be indented, at least 4 spaces per indentation level. Statements at the same nesting level should be at the same indentation level; statements at deeper nesting levels should be indented more. (For the purposes of this standard, the keyword "else" is regarded as having the same nesting level as the "if" it corresponds to.) For example, the following indentation practices are not permitted: if (condition) statement-group; if (condition) statement-group; else statement-group; if (condition) for (init; test; step) statement-group; if (condition) statement-group; else statement group; (S) Nesting the trinary conditional operator (?:) is not permitted. (P) For internal formatting and indenting style, the following is recommended: . 4-space indentations at each level; . braces delineating blocks used in the style of if (exp) { code } or if (exp) { code } . a separate declaration statement for each pointer, due to the confusion that can arise when reading and modifying a declaration like char *a, b, *c; . comments lined up systematically; . spaces between reserved words and their opening parentheses, e.g., if (condition) rather than if(condition); . no deep nesting (greater than 4 levels deep) . statement blocks less than 1 page long . one statement per line . parentheses around the objects of sizeof and return. (P) Concerning internal comments: . Full English sentences are recommended. . It is often clearer and more readable to make small blocks of comments as "paragraph headers" to a block of code than to comment every line or so, especially if the code is straightforward and untricky (which most of it should be, especially if the programmer is conscientious about variable naming and datatype compatibility). . Anything non-obvious should be well-commented. (P) Concerning white space and other aids to readability and debugging: . blank lines should be used between blocks of code that are functionally distinct . in expressions, operators should be surrounded by blanks (but not operators which compose primaries, specifically ".", "->") . in a function definition, the function name and its datatype should appear on one line. Examples: int pread(...) SOMESTRUCT * function(param1, param2) This latter practice aids readability and the comparison of the definition of a routine with its uses. (P) Other suggestions for improving readability: . Side effects within expressions should be used sparingly. It is recommended that no more than one operator with a side effect (=, op=, ++, --) appear within an expression. Function calls with side effects count as operators for this purpose. . In an "if-else" chain, the form if (condition) statement; else if (condition) statement; else if (condition) statement; should only be used when the conditions are all of the same basic form: e.g., testing the same variable against different values. If the conditions are qualitatively different, the additional "if" statements should start on new lines, indented, as in if (cond) statement; else if (cond2) statement; else statement; . In the condition portion of an if, for, while, etc., side effects whose effect extends beyond the extent of the guarded statement block should be minimized. That is, in a block like if ((c = getc(file)) != EOF) { guarded-stmts } other-stmts it is natural to think of "c" being "bound" to a value only within the guarded-stmts; use of a variable set or modified in a condition, outside the range of the statements guarded by the condition, is quite distracting. . The use of || and && with right hand operands having side effects is discouraged. Also, whenever || and && are mixed in the same expression, parentheses should be used for clarity. 3. MODULARITY 3.1. Routine Length (P) Routines should be kept reasonably short. In general, a routine (or command) processes one or more inputs and generates one or more outputs, where each of the inputs and outputs can be concisely described. Usually a routine should only perform one function. Signs that a routine is too long, and ought to be split up, are: length greater than two pages; heavy use of "internal" variables (variables whose scope is less than the entire routine). 3.2. Shared Data and Include Files (S) Declarations of variables that are to be shared among several routines in a package should be placed at the beginning of the file containing the routines. If they are entirely internal to the package, they should be declared "static" to hide them from other files. (S) Declarations of structures and global variables used for communications between a package and its callers should be placed in an appropriately named .h file. Shared global variables should be declared extern in the .h file so that if the package which sets/uses them is accidentally not loaded, a diagnostic will be issued by the loader. (S) Definition and optional initialization of such globals should reside in one and only one file for each program. If a global is clearly associated with a specific package, it may be defined in the file for that package; otherwise, it should be placed in a file called data.c which is compiled and linked with the other routines when a program is being built. (P) Use of globals should be minimized by judicious use of parameters. Note that while static and extern designators in C both yield "common" storage allocation, static allows the named variable to be known only within the context in which it is declared; thus, an identifier declared static at the top of a file will only be known within the file. In addition, local symbolic constants (#defines) may occur anywhere within a routine, and may be placed below the #include directives if the writer feels that this aids readability. (S) Include files should contain all and only all of the following items necessary for a given program and shared among two or more of its files: . #defines . typedefs . extern declarations (S) Include files may also contain nested #include directives. However, this practice should be kept to a minimum. It is recommended that include files which may be embedded in this way contain a check to see whether they are being included twice, to avoid unnecessary preprocessor and compiler complaints when the user includes them both implicitly and explicitly. The simplest way to do this is to check for a special hidden #define, as in #ifdef _INCLUDEFILENAME #define _INCLUDEFILENAME . . Contents of include file . #endif _INCLUDEFILENAME 3.3 Routine interfaces (P) In general, a routine should be designed with a "natural", easily-remembered calling sequence. Routines with more than five arguments are not recommended. Routines with "op-code" arguments, where one argument determines the interpretation and functions of the others, are also not recommended (though they may prove useful as internal routines to a package, they should NOT be part of a package's documented interface). 4. PORTABILITY (P) Adherence to datatype compatibility should be practiced where reasonable. This can be facilitated by liberal use of C's typedef facility and explicit casting of types, as well as by the use of the union datatype. (P) The following violation of strict adherence is permitted: a package which returns a pointer to a structure whose format need not be known outside that package may return a "generic" pointer, of type (char *). It is recommended that the typedef PTR be used for this purpose; this typedef will be provided in some standard system file. Note that char* is specifically chosen because the language guarantees that any pointer may be converted to a char* and back again without harm. (S) Liberal use of #defines should eliminate "magic numbers", whether machine dependent or implementation dependent or arbitrary/random. (S) To the extent that the conditional compilation facility of C allows, non- portable constructions can use this facility. Failing this, machine or implementation dependent constructs should be visibly commented in the code. When using conditional compilation for portability purposes, be sure to use appropriate parameters, rather than machine type, wherever possible. For example, code which handles the C machine's 20 bit wordsize or 10 bit bytesize should use the parameter BYTESIZE in cpu.h rather than being ifdeffed on "mbb". (P) Up to six register variables can be declared (with some effect) on the C70 machine, but only three on the 11/70 (where additional ones are assigned regular automatic storage). Therefore, the first three register variables declared (in lexicographic order) should be ones for which the most gain can be gotten. Note that register variables, judiciously chosen, can be very good space/time savers, but the compiler is not overly smart about them, and can give you irritating "expression overflow" messages. In general, as with any "optimization", it is wise to design, code and debug first, and then add in register storage to one's declarations. 5. NAMING (P) Names should be chosen for their mnemonic nature. Recall that although there is a limit on the number of initial characters of a name that must be distinct in C (and for a given machine), this does not prevent any name from being longer if such length will aid readability. (S) It is a useful C convention to use upper-case for #defines and typedef names. (S) One exception to the above is for parameterized #defines. These may be in lower-case. ************************************************************************** The following was provided via FTP by Keith A. Lantz at Stanford <CSL.LANTZ at SU-SCORE> via FTP following the enquiry distributed via Arpanet BBOARDS. 1 NETWORK GRAPHICS C STYLE SHEET Andrew Shore, et al. Computer Systems Laboratory Stanford University Stanford, CA 94305 18 June 1982 1. Names Don't use capital letters in file names (except for V !?). Avoid the underscore. Global variables, procedures, structs, unions, typedefs, defined constants, and macros all begin with a capital letter, and are logically capitalized thereafter (e.g. MainHashTable). A global variable is one defined outside a procedure, even though it may not be exported from the file, or an external variable. The motivation for treating macros and constants this way is that they may then be freely changed to procedure calls or (global or external) variables. Local variables begin with a lower-case letter, but are logically capitalized thereafter (e.g. bltWidth, power, maxSumOfSquares). Fields within structures or unions are treated in this manner also. 2. Comments There are generally two types of comments: block-style comments, and on-the- line comments. Multi-line, block-style comments will follow the UNIX style of /* and */ appearing on lines by themselves, and the body of the comment will start with a properly aligned *. The comment should usually be surrounded by blank lines as well. The motivation for this is that it is easy to add/delete first and last lines, and it is easier to detect the common error of omitting the */ and thus including all code up to and including the next */ in a comment (Yapp helps with that too). /* * this is the first line of a multi-line comment, * this is another line * the last line of text */ On-line comments are used to detail declarations, and to explain single lines of code. And, I suppose, for brief (i.e. one line) block-style descriptive comments. 1 This work was supported by the Defense Advanced Research Projects Agency under contract number MDA903-80-C-0102. 2 Procedures are preceded by block-style comments, explaining their (abstract) function in terms of their parameters, results, and side effects. Note that the parameter declarations are indented, not flushed left. /* * Unblock: * unblock the process pd */ Unblock( pd ) register Process pd; /* the process to unblock */ { register Process *currPd, *tmpPd; register unsigned prio; prio = pd->priority; Disable; pd->state = Ready; /* Add pd to the ready queue */ currPd = (Process *) &ReadyqHead; while ((tmpPd = currPd->link) != Null) { if (tmpPd->priority > prio) break; currPd = tmpPd; } pd->link = tempPd; currPd->link = pd; Enable; } 3. Indenting The above example shows many of the indenting rules. Braces ( "{" and "}" ) appear alone on a line, and are indented two spaces from the statement they are to contain the body of, the body is indented two more spaces from the braces (for a total of four spaces). else's and else if's line up with their dominating if statement (to avoid marching off to the right, and to reflect the semantics of the statement). 3 if ((x = y) == 0) { flag = 1; printf (" the value was zero "); } else if (y == 1) { switch (today) { case Thursday: flag = 2; ThursdayAction(); break; case Friday: flag = 3; FridayAction(); break; default: OtherDayAction(); } } else printf(" y had the wrong value "); 4. File Contents I think we agreed on the following order for file contents. 1. initial descriptive comment (see example below) which contains: a. file name, with indication of the relative path to it when relevant b. brief descriptive abstract of contents c. a list of all defined procedures in their defined order d. list of authors e. list of current maintainers f. list of recent and major modifications in reverse chronological order with indication (initials) of who made the change. 2. included files (use relative path names whenever possible) 3. external definitions (imports and exports) 4. function declarations (externals and forward references) 4 5. constant declarations 6. macro definitions 7. type definitions 8. global variable declarations 9. procedure and function definitions Here is an example of the header comment: /* * FILE: libc/vkstuff/malloc.c * * CONTENTS: * C storage allocator stolen and hacked up from UNIX for the SUN * (NOTE: these were stolen and have the wrong naming conventions) * malloc * free * realloc * allock DEBUG ONLY! * SetBrk ! our routine to fake up sbrk() * * AUTHORS: stolen and hacked by Andrew I. Shore (shore) * * MAINTAINER: shore * * HISTORY: * 03/05/82 AIS replaced calls to UNIX sbrk() with calls to own version * SetBrk() for the sun/Vkernel */ 5. Parenthesis () We seem to have decided on the following conventions for parentheses. When parentheses enclose the expression for a statement (if, for, etc.), the parentheses `belong to' the expression, so there is a space between the keyword and the parenthesized expression. For function calls the parentheses `belong to' the call, so there is no space between function name and open paren (there may some inside the parentheses to make the expression list (argument list) look nice). if (Mumble()) { Grumble( (a = b) == 0 ); return (Nil); } else { Fumble( a, b, c ); return (ToSender); } 5 It is unclear what to do with return. Note, then, that it is operators that cause spaces on the outside of parentheses -- (a + b) * c. 6. General 1. One statement/declaration per line. 2. Make judicious use of blank lines. a. At least 3 blank lines between individual procedures. b. Blank lines surround "large" comments. 3. Make sure comments and code agree! 4. Don't just echo the code with comments -- make every comment count! i.e. nix on: /* add foo to bar */ bar += foo; i Table of Contents 1. Names 1 2. Comments 1 3. Indenting 2 4. File Contents 3 5. Parenthesis () 4 6. General 5 **************************************************************************

22 years, 10 months

Re: [TUHS] Can someone advise me regarding a gui for UNIX

by A.P.Garcia

> Can someone advise me regarding when the GUIs became a standard feature on > UNIX? Or operating systems whose ancestry was indeed UNIX? MIT/LCS/TR-368, _The X Window System_, by Scheifler and Gettys, is dated October 1986. Here are a couple paragraphs from the introduction: X is the result of the simultaneous need for a window system from two separate groups at MIT. In the summer of 1984, the Argus system [15] at the Laboratory for Computer Science needed a debugging environment for multi-process distributed applications, and a window system seemed the only viable solution. Project Athena [4] was faced with dozens, and eventually thousands of workstations with bitmap displays, and needed a window system to make the display useful. Both groups were starting with the Digital VS100 display [13] and VAX hardware, but it was clear at the outset that other architectures and displays had to be supported. In particular, IBM workstations with bitmap displays of unknown type were expected eventually within Project Athena. Portability was therefore a goal from the start. Although all of the initial implementation work was for Berkeley Unix, it was clear that the network protocol should not depend on aspects of the operating system. The name X derives from the lineage of the system. At Stanford University, Paul Asente and Brian Reid had begun work on the W window system [3], as an alternative to VGTS [12, 21] for the V system [5]. Both VGTS and W allow network-transparent access to the display, using the synchronous V communication mechanism. Both systems provide "text" windows for ASCII terminal emulation. VGTS provides graphics windows driven by fairly high-level object definitions from a structured display file; W provides graphics windows based on a simple display-list mechanism, with limited functionality. We acquired a Unix-based version of W for the VS100 (with synchronous communication over TCP [23]) done by Asente and Chris Kent at Digital's Western Research Laboratory. From just a few days of experimentation, it was clear that a network- transparent hierarchical window system was desirable, but that restricting the system to any fixed set of application-specific modes was completely inadequate. It was also clear that, although synchronous communication was perhaps acceptable in the V system (due to very fast networking primitives), it was completely inadequate in most other operating environments. X is our "reaction" to W. The X window hierarchy comes directly from W, although numerous systems have been built with hierarchy in at least some form [10, 14, 17, 27, 30, 31, 32, 33, 34, 35]. The asynchronous communication protocol used in X is a significant improvement over the synchronous protocol used in W, but is very similar to that used in Andrew [9, 19]. X differs from all of these systems in the degree to which both graphics functions and "system" functions are pushed back (across the network) as application functions, and in the ability to transparently tailor desktop management. 3. Asente. P. W Reference Manual. Stanford University, 1984. internal document. 4. Balkovich, E., Lerman, S., and Parmelee, R. "Computing in Higher Education: The Athena Experience". _Communications of the ACM 28_, 11 (Nov. 1985). 5. Cheriton, D. "The V Kernel: A Software Base for Distributed Systems". _IEEE Software 1_, 2 (April 1984). 9. Gosling, J. and Rosenthal, D. A Window-Manager for Bitmapped Displays and Unix. In _Methodology of Window-Managers_, F.R.A. Hopgood et al, Eds., Springer-Verlag, 1986. 10. Hawley, M. J., and Leffler, S. J. Windows for Unix at Lucasfilm. Summer Conference Proceedings, Portland, USENIX Association, 1985. 12. Lantz, K.A. and Nowicki, W.I. "Structured Graphics for Distributed Systems". _ACM Transactions on Graphics 3_, 1 (Jan. 1984). 13. Levy, H. "VAXstation: A General-Purpose Raster Graphics Architecture". _ACM Transactions on Graphics 3_, 1 (Jan. 1984). 14. Lipkie, D.E., Evans, S.R., Newlin, J.K., and Weissman, R.L. "Star Graphics: An Object-Oriented Implementation." _Computer Graphics 16_, 3 (July 1982). 15. Liskov, B. and Scheifler, R. "Guardians and Actions: Linquistic Support for Robust, Distributed Programs". _ACM Transactions on Programming Languages and Systems 5_, 3 (July 1983). 17. _Microsoft Windows: Programmer's Guide_. Microsoft Corporation, 1985. 19. Morris, J., et atl. "Andrew: A Distributed Personal Computing Environment". _Communications of the ACM 29_, 3 (March 1986). 21. Nowicki, W. _Partitioning of Function in a Distributed Graphics System_. Ph.D. Th., Stanford University, Stanford, CA, 1985. 23. Postel, J. Transmission Control Protocol. RFC 793, USC/Information Sciences Institute, Sept. 1981. 27. Stallman, R., Moon, D., and Weinreb, D. Lisp Machine Window System Manual. MIT Artificial Intelligence Laboratory, Aug., 1983. 30. _Programmer's Reference Manual for SunWindows_. Sun Microsystems, Inc., 1985. 31. Sweet, R. "Mesa Programming Environment". _ACM SIGPLAN Notices 20_, 7 (July 1985). 32. Sweetman, D. A Modular Window System for Unix. In _Methodology of Window-Managers_, F.R.A. Hopgood et al, Eds., Springer-Verlag, 1986. 33. _Programming the User Interface_. Symbolics, Inc., 1986. 34. Teitelman, W. The Cedar Programming Environment: A Midterm Report and Examination. CSL-83-11, Xerox PARC, June, 1984. 35. Trammel, R.D. A Capability Based Hierarchic Architecture for Unix Window Management. Summer Conference Proceedings, Portland, USENIX Association, 1985. two other references, not mentioned in the above text, that are worth noting: 11. _Information Processing: Graphical Kernel System (GKS) - Functional Description_. DIS 7942, International Standards Organization, 1982. 22. Pike, R. "The Blit: A Multiplexed Graphics Terminal". _AT&T Bell Laboratories Technical Journal 63_, 8 (Oct. 1984).

22 years, 10 months

[pups] Can someone advise me regarding a gui for UNIX

by Gregg C Levine

Hello from Gregg C Levine Cross posted to both TUH, and PUPS lists, apologies to all. Can someone advise me regarding when the GUIs became a standard feature on UNIX? Or operating systems whose ancestry was indeed UNIX? I know that with Linux, for example started carrying one, about the same time the kernel became capable of supporting it. Or at least that's my opinion. With regard to the materials we discuss here, well, that's what I am attempting to ascertain. Gregg C Levine drwho8(a)worldnet.att.net "Oh my!" The Second Doctor's nearly favorite phrase.

22 years, 10 months

E11 later versions and available boot images

by Gregg C Levine

Hello from Gregg C Levine Has anyone tried out the boot images, in that directory on E11 ver 3.1? It happens that I can get it to work, under Bochs, that is, I can run E11, there. I haven't as yet, tried any of the boot images, myself. Right now I'm downloading the ones that I am interested in. Gregg C Levine drwho8(a)worldnet.att.net "Oh my!" The Second Doctor's nearly favorite phrase.

22 years, 10 months

[pups] Interdata 3220 backup tape found... worth recovering for archives?

by Robertdkeys＠aol.com

I chanced upon some old V7 stuff today, from a researcher at the Duke University Medical Center that did not have the heart to just throw them out. There was a complete manual set for V7 from a Perkin-Elmer NMR machine dating from 1984, and a backup tape of the system (9 track Scotch 700 series 6250bpi) dated 12/17/80. The machine was apparently an Interdata 3220 (Perkin-Elmer was supposed to have bought out Interdata). The manuals will make for fun reading, but there may be some worthwhile bits if the tape is OK. Anyway, I am seriously thinking of trying to read the contents of the tape, and pass them on to Warren, for the archives, if he thinks that is something to do. As to reading the tape, with the highest chance for successful recovery, what would the list folks recommend. I was thinking of just doing a retension on the tape to wind it off the reel and prevent sticking, and then maybe use the copytape ditty that has been floating around the net since time began, which should list file sizes, block sizes, file types, etc., while reading the files to disk. I can roll the tape on a VAX or a Sparc system using a Cipher M995S deck. Any suggestions from the list? Thanks Bob Keys robertdkeys(a)aol.com

22 years, 10 months

[pups] Req help rebuilding v7 rl2unix with dz driver added

by Richard L. Hamilton

(running under simh V2.9-11) I wanted to add the dz driver for multi-"terminal" support. But I'm a bit stumped figuring out how to rebuild rl2unix, let alone how to add the dz driver. (no rlconf/rl2conf file, although mkconf.c looks like maybe it knows about the rl2 if not about the dz) Is this do-able? Is the dz driver in the v7 image usable? -- mailto:rlhamil@mindwarp.smart.net http://www.smart.net/~rlhamil

22 years, 10 months

Re: [TUHS] Re: Making boot disks

by pete＠dunnington.u-net.com

On Oct 1, 10:16, Ian Molton wrote: > On Tue, 1 Oct 2002 06:29:56 GMT > pete(a)dunnington.u-net.com (Pete Turnbull) wrote: > > It is indeed a straight port of BSD 4.x, where x depends in whether is > > it's RISC iX 1 or 1.2 (R440 used 4.2, I think; R260 used 4.3). > > was the only difference between 1 and 1.2 the kernel? I think other things were updated as well, in line with differenet versions of BSD, but I don't have any sort of definitive list. > > Take a look at James Carter's page at > > http://www.jfc.org.uk/documents/riscix_clone.html > > wont I need a working installation first? To clone a disk, yes, you need to start with a good disk :-) > > > is it possible for someone else to make a filesystem image for me > > > that I could dd onto a floppy? I suspect that this system uses an > > > old variant of ufs. > > > > It is a standard 4.3 filesystem (at least for the verison for an > > R260). It even says so when it boots: > > Thats good to know - linux can actually write to that (although attempts > so far have led to kernel panics!) > > Do you know of generic source for mkfs ? Linux source, especially early versions, or a full BSD 4.x distribution, eg from the PUPS archive? > > One of us could copy some stuff for you. I'm not sure you'd be able > > to get what you need onto a single floppy, though. That's not how > > Acorn did it. > > did you see the scripts I attached? > > Apparently the create 3 floppies, which can be used to install a system. I've looked at the scripts (sorry, didn't have time yesterday). They're not Acorn's. They were created by Granada Microcare's Field Service division when they had to upgrade R140 versions of RISC iX -- 1.13 was a bugfix release. They should work, providing the versions of the kernel and other files in my version will fit on a floppy. I'm not sure how best to get your tar file back though; it doesn't look like the minimal system has NFS support. You ought be able to do it if you had a spare hard drive, put the tar file on it, and mount it under /mnt. Modify the tar command in cpsys so it doesn't overwrite /mnt, like James and I did. dsplit is just a utility (written by Acorn?) to split a big file over several floppies, or extract it again (like bsplit, but probably with different markers). > can risciX do loopback mounted filesystems?) No. That's a linux invention. But I can probably create the floppies for you, when I have time to move my R260 to somewhere I can use it -- probably not this weekend, maybe the weekend after. What machine have you got? R140, R260, or something else? Is it the same type as the filesystem you copied came from? -- Pete Peter Turnbull Network Manager University of York

22 years, 10 months

Jump to page:

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

2001

2000

1999

1998

1997

1996

1995

1994

1993

1992

1991

1990

TUHS