/share/doc/psd/04.uprog/p9

  1.\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
  2.\" 
  3.\" Redistribution and use in source and binary forms, with or without
  4.\" modification, are permitted provided that the following conditions are
  5.\" met:
  6.\" 
  7.\" Redistributions of source code and documentation must retain the above
  8.\" copyright notice, this list of conditions and the following
  9.\" disclaimer.
 10.\" 
 11.\" Redistributions in binary form must reproduce the above copyright
 12.\" notice, this list of conditions and the following disclaimer in the
 13.\" documentation and/or other materials provided with the distribution.
 14.\" 
 15.\" All advertising materials mentioning features or use of this software
 16.\" must display the following acknowledgement:
 17.\" 
 18.\" This product includes software developed or owned by Caldera
 19.\" International, Inc.  Neither the name of Caldera International, Inc.
 20.\" nor the names of other contributors may be used to endorse or promote
 21.\" products derived from this software without specific prior written
 22.\" permission.
 23.\" 
 24.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
 25.\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
 26.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 27.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 28.\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
 29.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 32.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 33.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 34.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 35.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 36.\" 
 37.\" $FreeBSD$
 38.\"
 39.\"	@(#)p9	8.1 (Berkeley) 6/8/93
 40.\"
 41.sp 100
 42.TL
 43.ft R
 44Appendix \(em The Standard I/O Library
 45.AU
 46D. M. Ritchie
 47.AI
 48AT&T Bell Laboratories
 49Murray Hill, NJ 07974
 50.PP
 51The standard I/O library
 52was designed with the following goals in mind.
 53.IP 1.
 54It must be as efficient as possible, both in time and in space,
 55so that there will be no hesitation in using it
 56no matter how critical the application.
 57.IP 2.
 58It must be simple to use, and also free of the magic
 59numbers and mysterious calls
 60whose use mars the understandability and portability
 61of many programs using older packages.
 62.IP 3.
 63The interface provided should be applicable on all machines,
 64whether or not the programs which implement it are directly portable
 65to other systems,
 66or to machines other than the PDP-11 running a version of
 67.UC UNIX .
 68.SH
 691.  General Usage
 70.PP
 71Each program using the library must have the line
 72.P1
 73		#include <stdio.h>
 74.P2
 75which defines certain macros and variables.
 76The routines are in the normal C library,
 77so no special library argument is needed for loading.
 78All names in the include file intended only for internal use begin
 79with an underscore
 80.UL _
 81to reduce the possibility
 82of collision with a user name.
 83The names intended to be visible outside the package are
 84.IP \f3stdin\f1 10
 85The name of the standard input file
 86.IP \f3stdout\f1 10
 87The name of the standard output file
 88.IP \f3stderr\f1 10
 89The name of the standard error file
 90.IP \f3EOF\f1 10
 91is actually \-1, and is the value returned by
 92the read routines on end-of-file or error.
 93.IP \f3NULL\f1 10
 94is a notation for the null pointer, returned by
 95pointer-valued functions
 96to indicate an error
 97.IP \f3FILE\f1 10
 98expands to
 99.UL struct
100.UL _iob
101and is a useful
102shorthand when declaring pointers
103to streams.
104.IP \f3BUFSIZ\f1 10
105is a number (viz. 512)
106of the size suitable for an I/O buffer supplied by the user.
107See
108.UL setbuf ,
109below.
110.IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10
111.br
112are defined as macros.
113Their actions are described below;
114they are mentioned here
115to point out that it is not possible to
116redeclare them
117and that they are not actually functions;
118thus, for example, they may not have breakpoints set on them.
119.PP
120The routines in this package
121offer the convenience of automatic buffer allocation
122and output flushing where appropriate.
123The names
124.UL stdin ,
125.UL stdout ,
126and
127.UL stderr
128are in effect constants and may not be assigned to.
129.SH
1302.  Calls
131.nr PD .4v
132.LP
133.UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type;
134.nr PD 0
135.IP
136.br
137opens the file and, if needed, allocates a buffer for it.
138.UL filename
139is a character string specifying the name.
140.UL type
141is a character string (not a single character).
142It may be
143.UL \&"r" ,
144.UL \&"w" ,
145or
146.UL \&"a"
147to indicate
148intent to read, write, or append.
149The value returned is a file pointer.
150If it is
151.UL  NULL
152the attempt to open failed.
153.ne 3
154.nr PD .4v
155.LP
156.UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr;
157.nr PD 0
158.IP
159.br
160The stream named by
161.UL ioptr
162is closed, if necessary, and then reopened
163as if by
164.UL fopen .
165If the attempt to open fails,
166.UL  NULL
167is returned,
168otherwise
169.UL ioptr ,
170which will now refer to the new file.
171Often the reopened stream is
172.UL stdin
173or
174.UL stdout .
175.nr PD .4v
176.LP
177.UL int\ getc(ioptr)\ FILE\ *ioptr;
178.nr PD 0
179.IP
180returns the next character from the stream named by
181.UL ioptr ,
182which is a pointer to a file such as returned by
183.UL fopen ,
184or the name
185.UL stdin .
186The integer
187.UL  EOF
188is returned on end-of-file or when
189an error occurs.
190The null character
191.UL \e0
192is a legal character.
193.nr PD .4v
194.LP
195.UL int\ fgetc(ioptr)\ FILE\ *ioptr;
196.nr PD 0
197.IP
198.br
199acts like
200.UL getc
201but is a genuine function,
202not a macro,
203so it can be pointed to, passed as an argument, etc.
204.nr PD .4v
205.LP
206.UL putc(c,\ ioptr)\ FILE\ *ioptr;
207.nr PD 0
208.IP
209.br
210.UL putc
211writes the character
212.UL c
213on the output stream named by
214.UL ioptr ,
215which is a value returned from
216.UL fopen
217or perhaps
218.UL stdout
219or
220.UL stderr .
221The character is returned as value,
222but
223.UL  EOF
224is returned on error.
225.nr PD .4v
226.LP
227.UL fputc(c,\ ioptr)\ FILE\ *ioptr;
228.nr PD 0
229.IP
230.br
231acts like
232.UL putc
233but is a genuine
234function, not a macro.
235.nr PD .4v
236.LP
237.UL fclose(ioptr)\ FILE\ *ioptr;
238.nr PD 0
239.IP
240.br
241The file corresponding to
242.UL ioptr
243is closed after any buffers are emptied.
244A buffer allocated by the I/O system is freed.
245.UL fclose
246is automatic on normal termination of the program.
247.nr PD .4v
248.LP
249.UL fflush(ioptr)\ FILE\ *ioptr;
250.nr PD 0
251.IP
252.br
253Any buffered information on the (output) stream named by
254.UL ioptr
255is written out.
256Output files are normally buffered
257if and only if they are not directed to the terminal;
258however,
259.UL stderr
260always starts off unbuffered and remains so unless
261.UL setbuf
262is used, or unless it is reopened.
263.nr PD .4v
264.LP
265.UL exit(errcode);
266.nr PD 0
267.IP
268.br
269terminates the process and returns its argument as status
270to the parent.
271This is a special version of the routine
272which calls
273.UL fflush
274for each output file.
275To terminate without flushing,
276use
277.UL _exit .
278.nr PD .4v
279.LP
280.UL feof(ioptr)\ FILE\ *ioptr;
281.nr PD 0
282.IP
283.br
284returns non-zero when end-of-file
285has occurred on the specified input stream.
286.nr PD .4v
287.LP
288.UL ferror(ioptr)\ FILE\ *ioptr;
289.nr PD 0
290.IP
291.br
292returns non-zero when an error has occurred while reading
293or writing the named stream.
294The error indication lasts until the file has been closed.
295.nr PD .4v
296.LP
297.UL getchar();
298.nr PD 0
299.IP
300.br
301is identical to
302.UL getc(stdin) .
303.nr PD .4v
304.LP
305.UL putchar(c);
306.nr PD 0
307.IP
308.br
309is identical to
310.UL putc(c,\ stdout) .
311.nr PD .4v
312.nr PD .4v
313.ne 2
314.LP
315.UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
316.nr PD 0
317.IP
318.br
319reads up to
320.UL n-1
321characters from the stream
322.UL ioptr
323into the character pointer
324.UL s .
325The read terminates with a newline character.
326The newline character is placed in the buffer
327followed by a null character.
328.UL fgets
329returns the first argument,
330or
331.UL  NULL
332if error or end-of-file occurred.
333.nr PD .4v
334.nr PD .4v
335.LP
336.UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
337.nr PD 0
338.IP
339.br
340writes the null-terminated string (character array)
341.UL s
342on the stream
343.UL ioptr .
344No newline is appended.
345No value is returned.
346.nr PD .4v
347.LP
348.UL ungetc(c,\ ioptr)\ FILE\ *ioptr;
349.nr PD 0
350.IP
351.br
352The argument character
353.UL c
354is pushed back on the input stream named by
355.UL ioptr .
356Only one character may be pushed back.
357.ne 5
358.nr PD .4v
359.LP
360.UL printf(format,\ a1,\ ...)\ char\ *format;
361.br
362.UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
363.br
364.UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format;
365.br
366.nr PD 0
367.IP
368.UL printf
369writes on the standard output.
370.UL fprintf
371writes on the named output stream.
372.UL sprintf
373puts characters in the character array (string)
374named by
375.UL s .
376The specifications are as described in section
377.UL printf (3)
378of the
379.ul
380.UC UNIX
381.ul
382Programmer's Manual.
383.nr PD .4v
384.LP
385.UL scanf(format,\ a1,\ ...)\ char\ *format;
386.br
387.UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
388.br
389.UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format;
390.nr PD 0
391.IP
392.br
393.UL scanf
394reads from the standard input.
395.UL fscanf
396reads from the named input stream.
397.UL sscanf
398reads from the character string
399supplied as
400.UL s .
401.UL scanf
402reads characters, interprets
403them according to a format, and stores the results in its arguments.
404Each routine expects as arguments
405a control string
406.UL format ,
407and a set of arguments,
408.I
409each of which must be a pointer,
410.R
411indicating where the converted input should be stored.
412.if t .sp .4v
413.UL scanf
414returns as its value the number of successfully matched and assigned input
415items.
416This can be used to decide how many input items were found.
417On end of file,
418.UL EOF
419is returned; note that this is different
420from 0, which means that the next input character does not
421match what was called for in the control string.
422.nr PD .4v
423.LP
424.UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
425.nr PD 0
426.IP
427.br
428reads
429.UL nitems
430of data beginning at
431.UL ptr
432from file
433.UL ioptr .
434No advance notification
435that binary I/O is being done is required;
436when, for portability reasons,
437it becomes required, it will be done
438by adding an additional character to the mode-string on the
439.UL fopen
440call.
441.nr PD .4v
442.LP
443.UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
444.nr PD 0
445.IP
446.br
447Like
448.UL fread ,
449but in the other direction.
450.nr PD .4v
451.LP
452.UL rewind(ioptr)\ FILE\ *ioptr;
453.nr PD 0
454.IP
455.br
456rewinds the stream
457named by
458.UL ioptr .
459It is not very useful except on input,
460since a rewound output file is still open only for output.
461.nr PD .4v
462.LP
463.UL system(string)\ char\ *string;
464.nr PD 0
465.IP
466.br
467The
468.UL string
469is executed by the shell as if typed at the terminal.
470.nr PD .4v
471.LP
472.UL getw(ioptr)\ FILE\ *ioptr;
473.nr PD 0
474.IP
475.br
476returns the next word from the input stream named by
477.UL ioptr .
478.UL EOF
479is returned on end-of-file or error,
480but since this a perfectly good
481integer
482.UL feof
483and
484.UL ferror
485should be used.
486A ``word'' is 16 bits on the
487.UC PDP-11.
488.nr PD .4v
489.LP
490.UL putw(w,\ ioptr)\ FILE\ *ioptr;
491.nr PD 0
492.IP
493.br
494writes the integer
495.UL w
496on the named output stream.
497.nr PD .4v
498.LP
499.UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf;
500.nr PD 0
501.IP
502.br
503.UL setbuf
504may be used after a stream has been opened
505but before I/O has started.
506If
507.UL buf
508is
509.UL NULL ,
510the stream will be unbuffered.
511Otherwise the buffer supplied will be used.
512It must be a character array of sufficient size:
513.P1
514char	buf[BUFSIZ];
515.P2
516.nr PD .4v
517.LP
518.UL fileno(ioptr)\ FILE\ *ioptr;
519.nr PD 0
520.IP
521.br
522returns the integer file descriptor associated with the file.
523.nr PD .4v
524.LP
525.UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset;
526.nr PD 0
527.IP
528.br
529The location of the next byte in the stream
530named by
531.UL ioptr
532is adjusted.
533.UL offset
534is a long integer.
535If
536.UL ptrname
537is 0, the offset is measured from the beginning of the file;
538if
539.UL ptrname
540is 1, the offset is measured from the current read or
541write pointer;
542if
543.UL ptrname
544is 2, the offset is measured from the end of the file.
545The routine accounts properly for any buffering.
546(When this routine is used on
547.UC UNIX \& non-
548systems,
549the offset must be a value returned from
550.UL ftell
551and the ptrname must be 0).
552.ne 3
553.nr PD .4v
554.LP
555.UL long\ ftell(ioptr)\ FILE\ *ioptr;
556.nr PD 0
557.IP
558.br
559The byte offset, measured from the beginning of the file,
560associated with the named stream is returned.
561Any buffering is properly accounted for.
562(On
563.UC UNIX \& non-
564systems the value of this call is useful only
565for handing to
566.UL fseek ,
567so as to position the file to the same place it was when
568.UL ftell
569was called.)
570.nr PD .4v
571.LP
572.UL getpw(uid,\ buf)\ char\ *buf;
573.nr PD 0
574.IP
575.br
576The password file is searched for the given integer user ID.
577If an appropriate line is found, it is copied into
578the character array
579.UL buf ,
580and 0 is returned.
581If no line is found corresponding to the user ID
582then 1 is returned.
583.nr PD .4v
584.LP
585.UL char\ *malloc(num);
586.nr PD 0
587.IP
588.br
589allocates
590.UL num
591bytes.
592The pointer returned is sufficiently well aligned to be usable for any purpose.
593.UL NULL
594is returned if no space is available.
595.nr PD .4v
596.LP
597.UL char\ *calloc(num,\ size);
598.nr PD 0
599.IP
600.br
601allocates space for
602.UL num
603items each of size
604.UL size .
605The space is guaranteed to be set to 0 and the pointer is
606sufficiently well aligned to be usable for any purpose.
607.UL NULL
608is returned if no space is available .
609.nr PD .4v
610.LP
611.UL cfree(ptr)\ char\ *ptr;
612.nr PD 0
613.IP
614.br
615Space is returned to the pool used by
616.UL calloc .
617Disorder can be expected if the pointer was not obtained
618from
619.UL calloc .
620.nr PD .4v
621.LP
622The following are macros whose definitions may be obtained by including
623.UL <ctype.h> .
624.nr PD .4v
625.LP
626.UL isalpha(c)
627returns non-zero if the argument is alphabetic.
628.nr PD .4v
629.LP
630.UL isupper(c)
631returns non-zero if the argument is upper-case alphabetic.
632.nr PD .4v
633.LP
634.UL islower(c)
635returns non-zero if the argument is lower-case alphabetic.
636.nr PD .4v
637.LP
638.UL isdigit(c)
639returns non-zero if the argument is a digit.
640.nr PD .4v
641.LP
642.UL isspace(c)
643returns non-zero if the argument is a spacing character:
644tab, newline, carriage return, vertical tab,
645form feed, space.
646.nr PD .4v
647.LP
648.UL ispunct(c)
649returns non-zero if the argument is
650any punctuation character, i.e., not a space, letter,
651digit or control character.
652.nr PD .4v
653.LP
654.UL isalnum(c)
655returns non-zero if the argument is a letter or a digit.
656.nr PD .4v
657.LP
658.UL isprint(c)
659returns non-zero if the argument is printable \(em
660a letter, digit, or punctuation character.
661.nr PD .4v
662.LP
663.UL iscntrl(c)
664returns non-zero if the argument is a control character.
665.nr PD .4v
666.LP
667.UL isascii(c)
668returns non-zero if the argument is an ascii character, i.e., less than octal 0200.
669.nr PD .4v
670.LP
671.UL toupper(c)
672returns the upper-case character corresponding to the lower-case
673letter
674.UL c.
675.nr PD .4v
676.LP
677.UL tolower(c)
678returns the lower-case character corresponding to the upper-case
679letter
680.UL c .