ansistdio.c

vxworks libc库源代码

/* ansiStdio.c - ANSI `stdio' documentation */

/* Copyright 1984-2002 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01j,21jan02,jkf  SPR#72774, fread is checking for NULL on wrong arg
01i,12dec01,jkf  fixing SPR#72128, fread should check for NULL before bcopy.
01h,11nov01,jkf  SPR#70967, fread() returns wrong value when 3rd arg == 0
01g,17mar99,jdi  doc: updated w/ info about proj facility (SPR 25727).
01f,04feb99,dgp  document errno values
01e,10feb95,jdi  doc format tweak in fopen() and update for rhp changes in 01d.
01d,24jan95,rhp  doc: avoid 'L' in fprintf() and fscanf(), no long doubles 
                 in VxWorks (see SPR#3886)
01c,19jul94,dvs  doc tweak (SPR #2512)
01b,05mar93,jdi  documentation cleanup for 5.1.
01a,24oct92,smb  created.
*/

/*
DESCRIPTION
The header stdio.h declares three types, several macros, and many functions
for performing input and output.
.SS Types
The types declared are `size_t' and:
.iP `FILE' 12
object type capable of recording all the information needed to
control a stream, including its file position indicator, a pointer to its
associated buffer (if any), an error indicator that records whether a
read/write error has occurred, and an end-of-file indicator that records
whether the end of the file has been reached.
.iP `fpos_t'
object type capable of recording all the information needed to
specify uniquely every position within a file.
.SS Macros
The macros are NULL and:
.iP "_IOFBF, _IOLBF, _IONBF" 12 3
expand to integral constant expressions with distinct values, suitable
for use as the third argument to setvbuf().
.iP BUFSIZ
expands to an integral constant expression that is the size of the
buffer used by setbuf().
.iP EOF
expands to a negative integral constant expression that is returned by
several functions to indicate `end-of-file', that is, no more input from a
stream.
.iP FOPEN_MAX
expands to an integral constant expression that is the minimum number of
the files that the system guarantees can be open simultaneously.
.iP FILENAME_MAX
expands to an integral constant expression that is the size needed for an
array of `char' large enough to hold the longest file name string that
can be used.
.iP L_tmpnam
expands to an integral constant expression that is the size needed for
an array of `char' large enough to hold a temporary file name string
generated by tmpnam().
.iP "SEEK_CUR, SEEK_END, SEEK_SET"
expand to integral constant expressions with distinct values suitable
for use as the third argument to fseek().
.iP TMP_MAX
expands to an integral constant expression that is the minimum number of
file names generated by tmpnam() that will be unique.
.iP "`stderr', `stdin', `stdout'"
expressions of type "pointer to FILE" that point to the FILE objects
associated, respectively, with the standard error, input, and output streams.

STREAMS
Input and output, whether to or from physical devices such as terminals and
tape drives, or whether to or from files supported on structured storage
devices, are mapped into logical data streams, whose properties are more
uniform than their various inputs and outputs. Two forms of mapping are
supported: for text streams and for binary streams.

A text stream is an ordered sequence of characters composed into lines,
each line consisting of zero or more characters plus a terminating new-line
character.  Characters may have to be added, altered, or deleted
on input and output to conform to differing conventions for representing
text in the host environment.  Thus, there is no need for a one-to-one
correspondence between the characters in a stream and those in the external
representation.  Data read in from a text stream will necessarily compare
equal to the data that were earlier written out to that stream only if:
the data consists only of printable characters and the control characters
horizontal tab and new-line; no new-line character is immediately preceded
by space characters; and the last character is a new-line character.
Space characters are written out immediately before a new-line character
appears.

A binary stream is an ordered sequence of characters that can transparently
record internal data.  Data read in from a binary stream should compare
equal to the data that was earlier written out to that stream, under the
same implementation.  However, such a stream may have a
number of null characters appended to the end of the stream.
.SS "Environmental Limits"
VxWorks supports text files with lines containing at least 254 characters,
including the terminating new-line character.  The value of the macro
BUFSIZ is 1024.

FILES
A stream is associated with an external file (which may be a physical
device) by opening a file, which may involve creating a new file.
Creating an existing file causes its former contents to be discarded, if
necessary.  If a file can support positioning requests (such as a disk
file, as opposed to a terminal), then a file position indicator associated
with the stream is positioned at the start (character number zero) of the
file.  The file position indicator is maintained by subsequent reads,
writes, and positioning requests, to facilitate an orderly progression
through the file.  All input takes place as if characters were read by
successive calls to fgetc(); all output takes place as if characters were
written by successive calls to fputc().

Binary files are not truncated, except as defined in fopen() documentation.

When a stream is unbuffered, characters are intended to appear from the
source or at the destination as soon as possible.  Otherwise characters
may be accumulated and transmitted to or from the host environment as a
block.  When a stream is fully buffered, characters are intended to be
transmitted to or from the host environment as a block when the buffer is
filled.  When a stream is line buffered, characters are intended to be
transmitted to or from the host environment as a block when a new-line
character is encountered.  Furthermore, characters are intended to be
transmitted as a block to the host environment when a buffer is filled,
when input is requested on an unbuffered stream, or when input is requested on
a line-buffered stream that requires the transmission of characters from
the host environment.  VxWorks supports these characteristics via the
setbuf() and setvbuf() functions.

A file may be disassociated from a controlling stream by closing the file.
Output streams are flushed (any unwritten buffer contents are transmitted
to the host environment) before the stream is disassociated from the file.
The value of a pointer to a FILE object is indeterminate after the associated
file is closed (including the standard text streams).

The file may be subsequently reopened, by the same or another program
execution, and its contents reclaimed or modified (if it can be repositioned
at its start).

TASK TERMINATION
ANSI specifies that if the main function returns to its original caller or
if exit() is called, all open files are closed (and hence all output
streams are flushed) before program termination.  This does \f3not\fP
happen in VxWorks.  The exit() function does not close all files opened
for that task.  A file opened by one task may be used and closed by another.
Unlike in UNIX, when a VxWorks task exits, it is the responsibility of the
task to fclose() its file pointers, except `stdin', `stdout', and
`stderr'.  If a task is to be terminated asynchronously, use kill() and
arrange for a signal handler to clean up.

The address of the FILE object used to control a stream may be significant;
a copy of a FILE object may not necessarily serve in place of the original.

At program startup, three text streams are predefined and need not be opened
explicitly:  standard input (for reading conventional input), standard output
(for writing conventional output), and standard error (for writing diagnostic
output).  When opened, the standard error stream is not fully buffered; the
standard input and standard output streams are fully buffered if and only if
the stream can be determined not to refer to an interactive device.

Functions that open additional (non-temporary) files require a file name,
which is a string.  VxWorks allows the same file to be open multiple times
simultaneously.  It is up to the user to maintain synchronization between
different tasks accessing the same file.

FIOLIB
Several routines normally considered part of standard I/O -- printf(),
sprintf(), vprintf(), vsprintf(), and sscanf() -- are not implemented as part
of the buffered standard I/O library; they are
instead implemented in fioLib.  They do not use the standard I/O buffering
scheme.  They are self-contained, formatted, but unbuffered I/O
functions.  This allows a limited amount of formatted I/O to be achieved
without the overhead of the standard I/O library.

SEE ALSO:
fioLib,
.I "American National Standard for Information Systems -"
.I "Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h)

INTERNAL
This documentation module is built by appending the following files:

    clearerr.c
    fclose.c
    fdopen.c
    feof.c
    ferror.c
    fflush.c
    fgetc.c
    fgetpos.c
    fgets.c
    fileno.c
    fopen.c
    fprintf.c
    fputc.c
    fputs.c
    fread.c
    freopen.c
    fscanf.c
    fseek.c
    fsetpos.c
    ftell.c
    fwrite.c
    getc.c
    getchar.c
    gets.c
    getw.c
    perror.c
    putc.c
    putchar.c
    puts.c
    putw.c
    rewind.c
    scanf.c
    setbuf.c
    setbuffer.c
    setvbuf.c
    stdioLib.c
    stdioShow.c
    tmpfile.c
    tmpnam.c
    ungetc.c
    vfprintf.c
*/

/* clearerr.c - clear error file for stdio.h */

/* Copyright 1992-1993 Wind River Systems, Inc. */

/* 
modification history 
-------------------- 
01d,05mar93,jdi  documentation cleanup for 5.1.
01c,21sep92,smb  corrected first line of file.
01b,20sep92,smb  documentation additions
01a,29jul92,smb  taken from UCB stdio
*/ 
 
/*
DESCRIPTION
* Copyright (c) 1990 The Regents of the University of California.
* All rights reserved.
*
* This code is derived from software contributed to Berkeley by
* Chris Torek.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
*    notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
*    notice, this list of conditions and the following disclaimer in the
*    documentation and/or other materials provided with the distribution.
* 3. All advertising materials mentioning features or use of this software
*    must display the following acknowledgement:
*	This product includes software developed by the University of
*	California, Berkeley and its contributors.
* 4. Neither the name of the University nor the names of its contributors
*    may be used to endorse or promote products derived from this software
*    without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
NOMANUAL
*/

#include "vxWorks.h"
#include "stdio.h"

#undef	clearerr

/******************************************************************************
*
* clearerr - clear end-of-file and error flags for a stream (ANSI)
* 
* This routine clears the end-of-file and error flags for a specified stream.
*
* INCLUDE FILES: stdio.h 
*
* RETURNS: N/A
*
* SEE ALSO: feof(), ferror()
*/

void clearerr
    (
    FILE * fp		/* stream to clear EOF and ERROR flags for */
    )
    {
    __sclearerr(fp);
    }
/* fclose.c - close file  stdio.h */

/* Copyright 1992-1993 Wind River Systems, Inc. */

/*
modification history
--------------------
01c,05mar93,jdi  documentation cleanup for 5.1.
01b,20sep92,smb  documentation additions
01a,29jul92,jcf  added OBJ_VERIFY and memory reclaimation.
	   +smb  taken from UCB stdio
*/

/*
DESCRIPTION
 *
 * Copyright (c) 1990 The Regents of the University of California.
 * All rights reserved.
 *
 * This code is derived from software contributed to Berkeley by
 * Chris Torek.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *	This product includes software developed by the University of
 *	California, Berkeley and its contributors.
 * 4. Neither the name of the University nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.

INCLUDE FILE: stdio.h, stdlib.h, error.h

SEE ALSO: American National Standard X3.159-1989

NOMANUAL
*/

#include "vxWorks.h"
#include "stdio.h"
#include "errno.h"
#include "stdlib.h"
#include "objLib.h"
#include "private/stdioP.h"


/******************************************************************************
*