stdio.h

TINI的pop3的c代码

/* ---------------------------------------------------------------------------
 *  Copyright (C) 2003 Dallas Semiconductor Corporation, All Rights Reserved.
 * 
 *  Permission is hereby granted, free of charge, to any person obtaining a
 *  copy of this software and associated documentation files (the "Software"),
 *  to deal in the Software without restriction, including without limitation
 *  the rights to use, copy, modify, merge, publish, distribute, sublicense,
 *  and/or sell copies of the Software, and to permit persons to whom the
 *  Software is furnished to do so, subject to the following conditions:
 * 
 *  The above copyright notice and this permission notice shall be included
 *  in all copies or substantial portions of the Software.
 * 
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 *  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *  MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *  IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES
 *  OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *  OTHER DEALINGS IN THE SOFTWARE.
 * 
 *  Except as contained in this notice, the name of Dallas Semiconductor
 *  shall not be used except as stated in the Dallas Semiconductor
 *  Branding Policy.
 * ---------------------------------------------------------------------------
 */
#ifndef _STDIO
#define _STDIO

#include <stddef.h>

/** \file stdio.h
 *  \brief File and other IO functions
 *
 *  This library contains functions for file system operations
 *  and formatting input and output data.  The file system
 *  has been adapted from TINI's Java Runtime Environment
 *  to be able to be called from a C program.
 *  
 *  The file system must reside in contiguous memory.  The maximum size of the 
 *  file system is likely to be far beyond the needs of most/any applications.
 *  Following is a more rigorous definition of the maximum file system size 
 *  for those interested:
 *
 *  Pages in the file system are 256-byte blocks (on 256-byte boundaries).  
 *  The file system's memory manager has several overhead blocks to maintain
 *  some information on block allocation.  The number of overhead blocks cannot
 *  exceed 255 blocks (65280 bytes).  11 pages of overhead are consumed by 
 *  file system specific overhead.  The remaining possible overhead blocks are
 *  consumed by:
 *  <ul>
 *    <li> 5 bytes magic signature </li>
 *    <li> 'num_blocks' bytes for the free list </li>
 *    <li> 'maxfd' * 26 bytes for open file descriptors </li>
 *  </ul>
 *  This data must therefore fit into 244 pages (62464 bytes).  Assuming we
 *  use the usual 'maxfd' value of 8, this leaves space for a free list 
 *  covering 62251 blocks, which yields a little over 15 MB of file system.
 *  Note that the file system overhead eats into the total file system space.
 *
 *  For detailed information on the DS80C400 please see the
 *  <a href="http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf">
 *  High-Speed Microcontroller User's Guide: DS80C400 Supplement</a>.
 *
 *  \warning  Some functions in this library are <b>NOT</b> multi-process 
 *            safe--that is, if you call the same method from two different 
 *            processes at the same time, the parameters to the function 
 *            may be destroyed, yielding unpredictable results.  Consult
 *            each individual funtion's documentation for details on which
 *            functions are multi-process safe.
 */

/** Version number associated with this header file.  Should be the same as
 * the version number returned by the <i>#filesystem_version</i> function.
 * \sa #filesystem_version */
#define FS_VERSION        7


#ifndef NULL
 /** Definition for a null pointer.
  */
 #define NULL ((void *) 0)
#endif

#ifndef _SIZE_T
 /** Type definition for the amount of data to be written or read.
  */
 #define _SIZE_T
 typedef unsigned int size_t;
#endif

#ifndef _OFF_T
 /** Type definition for the offset in a file.
  */
 #define _OFF_T
 typedef unsigned int off_t;
#endif

#ifndef _FPOS_T
 /** Type definition for the position in a file.
  */
 #define _FPOS_T
 typedef long fpos_t;
#endif


/** Definition for file flag.  Denotes that the end of the file has been reached for this file.
 * \sa FILE */
#define FILE_FLAGS_EOF    1
/** Definition for file flag.  Denotes that this is a temporary file.
 * \sa FILE */
#define FILE_FLAGS_TEMP   2

/** Type for the file.  Currently, this file system only supports
 *  the TINI File System type.
 * \sa FILE
 */
#define FILE_TYPE_TINIFS  1

/** Structure for FILE object.  Includes file flags, last
 *  error code, file type, and a pointer to the file 
 *  descriptor.
 *
 */
struct file_structure
{
  int flags;                  ///< Flags for the file.  Can denote the EOF is reached, or that file is temporary.
  int error;                  ///< Last error code for the file.
  int type;                   ///< File type.  currently on the #FILE_TYPE_TINIFS is supported.
  void* fd;                   ///< Pointer to the file descriptor, used internally by the TINI File System.
  unsigned char* fname_copy;  ///< Copy of the name of the file used internally.  Destroyed on <i>#fclose</i>.
};

/** Type definition for a C file object.
 */
typedef struct file_structure FILE;

#pragma SAVE
#pragma REGPARMS

//Size of <stdio.h> buffers. 
// This doesn't really matter right now.  We may add it in the future.
//#define BUFSIZ         1024

/** Maximum size in bytes of the longest filename string 
 * that the implementation guarantees can be opened. 
 * \sa #fopen */
#define FILENAME_MAX   255

/** Number of streams which the implementation guarantees 
 * can be open simultaneously. 
 * \sa #fopen */
#define FOPEN_MAX      8

/** Maximum size of character array to hold #tmpnam output. 
 * \sa #tmpnam */
#define L_tmpnam       20


/** Seek offset is from the current location in the file.
 * \warning Option currently not supported.
 * \sa #fseek 
 * \sa #fseeko*/
#define SEEK_CUR       0x5555
/** Seek offset is from the end of the file.
 * \warning Option currently not supported.
 * \sa #fseek 
 * \sa #fseeko*/
#define SEEK_END       0x5556
/** Seek offset is from the beginning of the file.
 * \sa #fseek 
 * \sa #fseeko*/
#define SEEK_SET       0x5557

/** Maximum number of guaranteed unique file names that can
 * be created by the #tmpnam function.
 * \sa #tmpnam */
#define TMP_MAX        10

/** Define for end-of-file.
 */
#define EOF            -1

/** Default directory that temporary file names will 
 * be built into.
 * \sa #tmpnam */
#define P_tmpdir       "temp"

/**
 * \brief     Clear the error indicators for a file stream.
 *
 * Clears the error and end-of-file indicators for a file stream.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  file handle to file to clear error flag for
 *
 */
//---------------------------------------------------------------------------
void     clearerr(FILE* f_handle);                                               

/**
 * \brief     Closes the file stream.
 *
 * Closes the stream associated with <i>f_handle</i>.  In the TINI File 
 * System, there are no buffers, so this function has nothing to flush
 * before closing. 
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle   handle of file to close
 *
 * \return    Always 0
 *
 * \sa        #fopen
 */
//---------------------------------------------------------------------------
int      fclose(FILE* f_handle);                                                 

/**
 * \brief     Checks to see if this stream has reached the end of the file.
 *
 * Tests the end-of-stream indicator for this file stream.  
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle to file to check end-of-file condition for
 *
 * \return    Non-zero if the end of the file has been reached, otherwise 0
 *
 */
//---------------------------------------------------------------------------
int      feof(FILE* f_handle);                                                   

/**
 * \brief     Gets the error indicator for the file stream.
 *
 * Gets the current error indicator for the file stream.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle to file to get current error code for
 *
 * \return    Current error code for file denoted by <i>f_handle</i>.  0 means
 *            no error.
 *
 */
//---------------------------------------------------------------------------
int      ferror(FILE* f_handle);                                                 

/**
 * \brief     Gets the next unsigned character from the file stream.
 *
 * Returns the next unsigned character (if available) from the file 
 * stream (converted to an int), advancing the file position pointer.  
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle of the file we will read from
 *
 * \return    The next character from the file, or #EOF if the end of file 
 *            has been reached
 *
 * \sa        #getc 
 * \sa        #feof
 * \sa        #fputc
 */
//---------------------------------------------------------------------------
int      fgetc(FILE* f_handle);                                                  

/**
 * \brief     Gets the current value of the file position indicator.
 *
 * Puts the current value of the file position indicator into the location
 * <i>position</i>.  The value in <i>position</i> after the function call
 * is to be used for resetting the stream to this position using a 
 * later call to <i>#fsetpos</i>.
 *
 * \warning   This function is not multi-process safe.  If two processes
 *            try to call this function at the same time, its parameters
 *            may be destroyed, yielding unpredictable results.
 * 
 * \param     f_handle  handle to file to get current position for
 * \param     position  pointer to location for position information
 *
 * \return    Always 0
 *
 * \sa        #fsetpos
 * \sa        #ftell
 */
//---------------------------------------------------------------------------
int      fgetpos(FILE* f_handle, fpos_t* position);                              

/**
 * \brief     Reads a string from the file stream.
 *
 * Reads at most <i>num</i>-1 characters from the file stream.  Will not 
 * return any data read after a newline character (which is included)
 * or the end of the file.  A null character is appended to the data read.
 *
 * Note that the implementation of this method is not efficient.  For more
 * efficient reading of data, use the <i>#fread</i> function.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     string    buffer to write string data to
 * \param     num       read a maximum of (<i>num</i>-1) bytes, leaving 1 for a terminating 0
 * \param     f_handle  handle to file to read from
 *
 * \return    Input pointer <i>string</i>, or #NULL if #EOF or 
 *            errors were encountered.  Data will be written as 0-terminated 
 *            string to <i>string</i>
 *
 * \sa        #fread
 * \sa        #fputs
 * \sa        #feof
 */
//---------------------------------------------------------------------------
char*    fgets(char* string, int num, FILE* f_handle);                           

/**
 * \brief     Opens the specified file.
 *
 * Opens the file specified and associates a stream with it.
 * Files can be opened in read, write, or append mode.  
 *
 * \warning   This function is not multi-process safe.  If two processes
 *            try to call this function at the same time, its parameters
 *            may be destroyed, yielding unpredictable results.
 *
 * \param     filename   name of the file to get a handle for
 * \param     mode - If mode[0] == 'r', open a reading file stream.
 *                   If mode[0] == 'a', open a writing stream for appending.
 *                   If mode[0] == 'w', open a writing stream for a blank file.
 *
 * \return    handle to the file, or #NULL on failure
 *
 * \sa        #freopen
 * \sa        #fclose
 */
//---------------------------------------------------------------------------
FILE*    fopen(const char* filename, const char* mode);                          

/**
 * \brief     Writes a character to a file stream.
 *
 * Writes the specified character (converted from an int) to a file stream,
 * advancing the file position indicator.  
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     ch        character that will be written to the file 
 *                      <i>f_handle</i>
 * \param     f_handle  handle of the file we will write character to
 *
 * \return    Character written if successful, else #EOF
 *
 * \sa        #fgetc
 * \sa        #putc
 */
//---------------------------------------------------------------------------
int      fputc(int ch, FILE* f_handle);                                          

/**
 * \brief     Writes a string to a file stream.
 *
 * Writes a null-terminated string to a file stream.  The terminating
 * character is not written.
 *
 * \warning   This function is not multi-process safe.  If two processes
 *            try to call this function at the same time, its parameters
 *            may be destroyed, yielding unpredictable results.
 * 
 * \param     str       null-terminated string to write to a file