1 10/31/90 HH07 Multics C User's Guide
2 Errata Information for MR12.4
3
4
5 pg 2-4: replace the section "Size of Data Types" with the |
6 following in order to include the examples. |
7 |
8 _^HS_^Hi_^Hz_^He _^Ho_^Hf _^HD_^Ha_^Ht_^Ha _^HT_^Hy_^Hp_^He_^Hs |
9 |
10 A program may need to know the size of a particular data |
11 type. If this is hardcoded into the program, the code will |
12 not be portable if the data type sizes between the two |
13 machines differ. For example, a program may use the maximum |
14 size of an int in an expression as follows: |
15
16
17 #define MAXINT 32767 /* largest int on a machine with |
18 a 16 bit int */ |
19 . |
20 . |
21 . |
22 if y == MACINT ....... |
23 |
24 This code could cause incorrect results on Multics. Multics |
25 has a 36-bit integer so the value of MAXINT is not the |
26 maximum integer size on the Multics hardware. The following |
27 code would correct the situation: |
28 |
29 #define MAXINT int unsigned - 1 >> 1 |
30
31
32 The following examples illustrate nonportable and portable |
33 ways of coding word definitions. |
34 |
35 Nonportable Example: |
36 |
37 #define word 4 /* hardcoded number of bytes in an |
38 integer */ |
39 |
40 Portable Example: |
41 |
42 #define word sizeofint |
43
44
45 pg 2-6: replace the page with the following in order to include |
46 the examples. |
47 |
48 To fix the problem, the Multics C programmer must define |
49 these functions as returning a long or a pointer. While |
50 returning a pointer in a long is allowed, it is not |
51 recommended. |
52 |
53 The following code samples illustrate nonportable and |
54 portable cases of returning a pointer as an integer. |
55
56
57 Nonportable Example: |
58
59
60 my_func /* function returns an int as default */ |
61 |
62 int *p; /* a pointer to an int */ |
63 |
64 if some_test return p; |
65 /* returns a pointer in an integer */ |
66 |
67 |
68
69
70 Portable Example: |
71 |
72 int *my_func /* function returns pointer to an int */ |
73 |
74 int *p; /* a pointer to an int */ |
75 |
76 return p; /* returns a pointer in a pointer |
77 location */ |
78 |
79 |
80 The following example shows a nonportable case of an integer |
81 holding a pointer, followed by a portable fix for Multics: |
82
83
84 Nonportable Example: |
85 |
86 int i; |
87 struct |
88 char y10; |
89 int p; |
90 qbert, *t; |
91 t = &qbert; /* t points to structure */ |
92 i = t; /* assign pointer to integer */|
93 i += 5; /* point to y5 */ |
94
95
96 Portable Example: |
97 |
98 char *p; |
99 |
100 p = &qbert.y0; /* point to start of y */ |
101 p += 5; /* point to y5 */ |
102 |
103 Be careful when you use pointers. Pointers on a VAX |
104 implementation are automatically initialized to zero when |
105 the stack frame is first allocated. Since zero is also the |
106 NULL value, the pointers can be used with no |
107 pre-initialization. |
108
109
110 pg 2-7: replace the first part of the page with the following in |
111 order to include the examples. |
112 |
113 On Multics, you get no automatic initialization, therefore, |
114 a pointer must be initialized explicitly to NULL before it |
115 is used. The following examples illustrate nonportable and |
116 portable cases of this. |
117
118
119 Nonportable Example: |
120 |
121 int *y10; |
122 if y3 == NULL.........; |
123 /* no guarantee that y3 has been assigned |
124 to NULL */ |
125 |
126 Portable Example: |
127 |
128 int *y10 = NULL NULL ....; |
129 /* explicitly initialize array of pointer to NULL */ |
130
131
132 _^HT_^Hh_^He _^HN_^Hu_^Hl_^Hl _^HP_^Ho_^Hi_^Hn_^Ht_^He_^Hr _^HV_^Ha_^Hl_^Hu_^He |
133 |
134 In most implementations the null pointer value NULL is |
135 defined to be the int value 0. It is not uncommon to see |
136 NULL used as a substitute for 0. On Multics the pointer |
137 value NULL is not 0, but -1|1. |
138 |
139 The following two examples show implementations in which |
140 NULL is 0, which could cause portability problems: |
141
142
143 Example 1 |
144 |
145 int p; |
146 |
147 if p == NULL...... |
148 /* use Null as substitute for zero */ |
149 |
150 Example 2 |
151 |
152 int *t10; |
153 |
154 tNULL = 0; |
155 /* NULL used as subscript zero */ |
156
157
158 pg 3-2 to 3-3: replace the documentation for "c_compile" with
159 the following.
160
161 cc
162
163 SYNTAX: cc pathnames -control_args
164
165 FUNCTION: cc is used to process and link-edit C programs.
166 cc will process input files and generate a single
167 link-edited object. When invoked with multiple pathnames,
168 cc will also leave unlinked object segments with a '.cob'
169 suffix for each file assembled. cc will invoke the C
170 preprocessor, the C Compiler, the assembler, and the Linkage
171 Editor as appropriate for each input file.
172
173
174 ARGUMENTS:
175 pathnames
176 are pathnames of files that are to be processed; the
177 amount of processing is determined by the pathname's
178 suffix such as '.c' '.cpp' '.cob' or '.alm' .
179 cc processes files in phases by invoking the C
180 preprocessor, then the C Compiler, then the assembler,
181 and then finally the Linkage Editor. Pathnames that have
182 the '.c' suffix are processed by all phases. Pathnames
183 that have the '.cpp' suffix start with the C Compiler
184 phase. Pathnames that have the '.alm' suffix start with
185 the assembly phase. All other pathnames are processed by
186 only the final Linkage Editor phase.
187
188
189 CONTROL ARGUMENTS:
190 -brief, -bf
191 Suppress printing of messages that state the current pass
192 being performed. Default
193
194 -definition args, -def args
195 Specifies define names to be defined or undefined in the
196 preprocessor, where "args" is a list of define names
197 separated by commas with no spaces in the following
198 form:
199
200 -def n,x=2,^y
201
202
203 The first arg specifies that n is to be defined as 1 in
204 the same way as '#define n' would define n to be 1. The
205 second arg specifies that x is to be given a definition
206 of 2 and the last arg specifies that y is to be undefined
207 in the preprocessor. A maximum of ten defines and ten
208 undefines are allowed.
209
210 -include paths, -incl paths
211 Specifies the pathnames of include file directories the
212 user wishes the preprocessor to look in for include
213 files. All arguments up to the next control argument are
214 treated as include directory pathnames. A maximum of ten
215 include directories can be specified.
216
217
218 -library paths, -lb paths
219 Specifies the pathnames of library directories, archives
220 or object files the user wishes the Linkage Editor to use
221 when resolving external references. All arguments up to
222 the next control argument are treated as include library
223 pathnames. A maximum of ten libraries can be specified.
224
225 -list, -ls
226 Specifies that a Linkage Editor listing file should be
227 generated for the Linkage Editor pass of c_compile. The
228 listing file will specify where the objects brought in by
229 the Linkage Editor were found.
230
231
232 -long, -lg
233 Specifies that a message should be printed specifying the
234 completion of each pass of the compiler for each
235 specified pathname.
236
237 -output_file pathname, -of pathname
238 Forces the output to be placed in the file defined by
239 pathname. If no output file name is given the output
240 will be put into the Linkage Editor's default output file
241 'a.out'.
242
243
244 -stop_after pass, -spaf pass
245 Tells cc to stop after the specified pass of the
246 compiler. Valid values for pass are:
247
248 preprocessor, pp: generates a ".cpp" file which is the
249 output from the preprocessor.
250
251 c: generates a ".alm" file which is an alm source file
252 which is the output from the C compiler.
253
254 alm: generates a ".cob" file which is the intermediate
255 executable file which is the output from the
256 assembler. This file is normally used as the input
257 to the Linkage Editor.
258
259
260 -table, -tb
261 Generates a full symbol table for use by symbolic
262 debuggers. The symbol table is part of the symbol
263 section of the object program and consists of two parts:
264 a statement map that gives the correspondence between
265 source line numbers and object locations of the source,
266 and an identifier table containing information about
267 every identifier referenced in the source program.
268
269 NOTES:
270 C_compile has been altered to use the standard search rules
271 to find the default C runtime library runtime.archive.
272 This library is normally located in >sl3p>cc>e and will be
273 found automatically by the referencing_dir search rule.
274
275
276 pg 4-59: for the "execve" routine, add the following description
277 to the RETURN VALUE section.
278
279 The return value will take on the following format. If an
280 error occurs during the creation of the child, errno will be
281 set to indicate the error and the return value will be
282 negative. Otherwise, the return value will give information
283 about the termination of the child process as follows:
284
285
286 RETURN VALUE <= EXIT STATUS|CORE BIT|SIGNAL NUMBER
287
288
289 EXIT STATUS is an 8 bit value sign extended to fill out the
290 rest of the word specified as an argument to the exit
291 function.
292
293 CORE BIT is a single bit value that indicates that a core
294 dump has been generated this value will always be zero on
295 Multics.
296
297 SIGNAL NUMBER is a 7 bit value representing the signal
298 number that may have caused the child's termination Example
299 SIGFPE = 8.
300
301 Note: because of sign extension, a negative EXIT STATUS
302 will result in a negative return value.
303
304
305 pg 4-158: insert the following documentation for the "putenv" |
306 routine between the "putchar" routine pg 4-158 and the |
307 "puts" routine pg 4-159. |
308 |
309 _^Hp_^Hu_^Ht_^He_^Hn_^Hv |
310 |
311 Changes or adds value to environment. |
312 |
313 SYNTAX: |
314 |
315 int putenv string |
316 char *string; |
317
318
319 ARGUMENTS: |
320 |
321 string |
322 Points to a string of the form "name=value". |
323 |
324 |
325 DESCRIPTION: |
326 |
327 Putenv makes the value of the environment variable name |
328 equal to value by altering an existing variable or |
329 creating a new one. In either case, the string pointed |
330 to by string becomes part of the environment, so |
331 altering the string will change the environment. The |
332 space used by string is no longer used once a new |
333 string-defining name is passed to putenv. |
334
335
336 DIAGNOSTICS: |
337 |
338 Putenv returns non-zero if it was unable to obtain |
339 enough space via malloc for an expanded environment; |
340 otherwise, it returns zero. |
341
342
343 RELATED FUNCTIONS: |
344 |
345 exec, getenv, malloc, environ |
346
347
348 WARNINGS: |
349 |
350 Putenv manipulates the environment pointed to by |
351 environ, and can be used in conjunction with getenv. |
352 However, envp the third argument to main is not |
353 changed. This routine uses malloc to enlarge the |
354 environment. After putenv is called, environmental |
355 variables are not in alphabetical order. A potential |
356 error is to call putenv with an automatic variable as |
357 the argument, then exit the calling function while |
358 string is still part of the environment. |
359
360
361 pg 4-196: for the "system" routine, add a new section RETURN
362 VALUE with the information below.
363
364 RETURN VALUE:
365
366 The return value will take on the following format. If an
367 error occurs during the creation of the child, errno will be
368 set to indicate the error and the return value will be
369 negative. Otherwise, the return value will give information
370 about the termination of the child process as follows:
371
372 RETURN VALUE <= EXIT STATUS|CORE BIT|SIGNAL NUMBER
373
374
375 EXIT STATUS is an 8 bit value sign extended to fill out the
376 rest of the word specified as an argument to the exit
377 function.
378
379 CORE BIT is a single bit value that indicates that a core
380 dump has been generated this value will always be zero on
381 Multics.
382
383 SIGNAL NUMBER is a 7 bit value representing the signal
384 number that may have caused the child's termination Example
385 SIGFPE = 8.
386
387 Note: because of sign extension, a negative EXIT STATUS
388 will result in a negative return value.