1 /* SETBUF.C

     2  * 

     3  * Portions Copyright (c) 1990-1999 Nokia Corporation and/or its subsidiary(-ies).

     4  * All rights reserved.

     5  */

     6 

     7 /*

     8  * Copyright (c) 1990 The Regents of the University of California.

     9  * All rights reserved.

    10  *

    11  * Redistribution and use in source and binary forms are permitted

    12  * provided that the above copyright notice and this paragraph are

    13  * duplicated in all such forms and that any documentation,

    14  * advertising materials, and other materials related to such

    15  * distribution and use acknowledge that the software was developed

    16  * by the University of California, Berkeley.  The name of the

    17  * University may not be used to endorse or promote products derived

    18  * from this software without specific prior written permission.

    19  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR

    20  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED

    21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

    22  */

    23 

    24 /*

    25 FUNCTION

    26 <<setbuf>>---specify full buffering for a file or stream

    27 

    28 INDEX

    29 	setbuf

    30 

    31 ANSI_SYNOPSIS

    32 	#include <stdio.h>

    33 	void setbuf(FILE *<[fp]>, char *<[buf]>);

    34 

    35 TRAD_SYNOPSIS

    36 	#include <stdio.h>

    37 	void setbuf(<[fp]>, <[buf]>)

    38 	FILE *<[fp]>;

    39 	char *<[buf]>;

    40 

    41 DESCRIPTION

    42 <<setbuf>> specifies that output to the file or stream identified by <[fp]>

    43 should be fully buffered.  All output for this file will go to a

    44 buffer (of size <<BUFSIZ>>, specified in `<<stdio.h>>').  Output will

    45 be passed on to the host system only when the buffer is full, or when

    46 an input operation intervenes.

    47 

    48 You may, if you wish, supply your own buffer by passing a pointer to

    49 it as the argument <[buf]>.  It must have size <<BUFSIZ>>.  You can

    50 also use <<NULL>> as the value of <[buf]>, to signal that the

    51 <<setbuf>> function is to allocate the buffer.

    52 

    53 WARNINGS

    54 You may only use <<setbuf>> before performing any file operation other

    55 than opening the file.

    56 

    57 If you supply a non-null <[buf]>, you must ensure that the associated

    58 storage continues to be available until you close the stream

    59 identified by <[fp]>.

    60 

    61 RETURNS

    62 <<setbuf>> does not return a result.

    63 

    64 PORTABILITY

    65 Both ANSI C and the System V Interface Definition (Issue 2) require

    66 <<setbuf>>.  However, they differ on the meaning of a <<NULL>> buffer

    67 pointer: the SVID issue 2 specification says that a <<NULL>> buffer

    68 pointer requests unbuffered output.  For maximum portability, avoid

    69 <<NULL>> buffer pointers.

    70 

    71 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,

    72 <<lseek>>, <<read>>, <<sbrk>>, <<write>>.

    73 */

    74 

    75 #include <stdio.h>

    76 #include "LOCAL.H"

    77 

    78 /**

    79 Change stream buffering.

    80 Changes the buffer used for I/O operations with the specified stream, or,

    81 if the specified buffer is NULL it disables buffering with the stream.

    82 This function should be called once the file associated with the stream 

    83 has been opened but before any input or output operation has been done.

    84 With buffered streams writing operations do not write directly 

    85 to the device associated with them; the data is accumulated in the buffer 

    86 and written to the device as a block.

    87 All buffers are also flushed when program terminates.

    88 @param fp pointer to an open file.

    89 @param buf User allocated buffer. Must have a length of BUFSIZ bytes.

    90 */

    91 EXPORT_C void setbuf (FILE * fp, char *buf)

    92 {

    93   (void) setvbuf (fp, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

    94 }