stdio.h

TINI的pop3的c代码

 * \param     f_handle  handle to file to write string to
 *
 * \return    number of bytes written, or #EOF on failure
 *
 * \sa        #fgets
 * \sa        #fwrite
 */
//---------------------------------------------------------------------------
int      fputs(const char* str, FILE* f_handle);                                 

/**
 * \brief     Read a number of bytes from a file stream.
 *
 * Reads a block of data from a file stream.  This function allows you to 
 * read <i>num</i> elements of size <i>size</i>.  However, note that this 
 * function always behaves as if it had been called by:
 * <code><pre>
 *       fread(ptr, 1, size*num, f_handle);
 * </pre></code>
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     ptr       pointer to buffer to read data into
 * \param     size      size of each element to be read
 * \param     num       number of elements to read
 * \param     f_handle  handle to file to read from
 *
 * \return    number of elements read
 *
 * \sa        #fgetc
 * \sa        #fwrite
 */
//---------------------------------------------------------------------------
size_t   fread(void* ptr, size_t size, size_t num, FILE* f_handle);              

/**
 * \brief     Associates an open stream with a different file.
 *
 * Closes the file associated with <i>old_handle</i> and opens a stream 
 * to the file <i>newfilename</i>.  
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     newfilename  name of file to open
 * \param     mode         mode to open <i>newfilename</i> in (see <i>#fopen</i> for details)
 * \param     old_handle   file handle to flush and close
 *
 * \return    Handle to file <i>newfilename</i>, or #NULL if the file could 
 *            not be opened.
 *
 * \sa        #fopen
 * \sa        #fclose
 */
//---------------------------------------------------------------------------
FILE*    freopen(const char* newfilename, const char* mode, FILE* old_handle);   

/**
 * \brief     Sets the file position indicator.
 *
 * Sets the file position indicator for a file stream.  Note that 
 * the only currently supported value for <i>tag</i> is
 * #SEEK_SET, meaning that the value <i>offset</i> wil always
 * be interpreted as the offset from the beginning of the file.
 * 
 * After a call to <i>#fseek</i>, the end-of-file indicator
 * for the file stream is reset.
 *
 * This function behaves the same as <i>#fseeko</i>.  The only
 * difference is that <i>#fseeko</i> accepts an <i>offset</i>
 * parameter of type #off_t.
 *
 * \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 of file to set posision for
 * \param     offset    offset to set for file position
 * \param     tag       only #SEEK_SET is supported
 *
 * \return    Always 0.
 *
 * \sa        #ftell
 * \sa        #fseeko
 * \sa        #fsetpos
 */
//---------------------------------------------------------------------------
int      fseek(FILE* f_handle, long int offset, int tag);                        

/**
 * \brief     Sets the file position indicator.
 *
 * Sets the file position indicator for a file stream.  Note that 
 * the only currently supported value for <i>tag</i> is
 * #SEEK_SET, meaning that the value <i>offset</i> wil always
 * be interpreted as the offset from the beginning of the file.
 * 
 * After a call to <i>#fseeko</i>, the end-of-file indicator
 * for the file stream is reset.
 *
 * This function behaves the same as <i>#fseek</i>.  The only
 * difference is that <i>#fseek</i> accepts an <i>offset</i>
 * parameter of type <b>long int</b>.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle of file to set posision for
 * \param     offset    offset to set for file position
 * \param     tag       only #SEEK_SET is supported
 *
 * \return    Always 0.
 *
 * \sa        #ftello
 * \sa        #fseek
 * \sa        #fsetpos
 */
//---------------------------------------------------------------------------
int      fseeko(FILE* f_handle, off_t offset, int tag);                          

/**
 * \brief     Sets the file position indicator.
 *
 * Sets a stream's file position indicator from the position information
 * pointed to by <i>position</i>.  The value in <i>position</i> should
 * have been obtained by a call to <i>#fgetpos</i>.  If successful,
 * this function will also clear the end-of-file indicator for the stream.
 *
 * \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 of file we will set the position for
 * \param     position  position in the file to set
 *
 * \return    Always 0
 *
 * \sa        #fgetpos
 * \sa        #fseek
 */
//---------------------------------------------------------------------------
int      fsetpos(FILE* f_handle, const fpos_t* position);                        

/**
 * \brief     Gets the file position indicator.
 *
 * Gets the file position indicator for the specified file.  This is the 
 * number of characters from the beginning of the file.  
 *
 * This function behaves the same as <i>#ftello</i>.  The only
 * difference is that <i>#ftello</i> returns a value of type #off_t.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle of file to get current position of
 *
 * \return    Current position in file, or -1L on failure.
 *
 * \sa        #fseek
 * \sa        #ftello
 * \sa        #fgetpos
 */
//---------------------------------------------------------------------------
long     ftell(FILE* f_handle);                                                  

/**
 * \brief     Gets the file position indicator.
 *
 * Gets the file position indicator for the specified file.  This is the 
 * number of characters from the beginning of the file.  
 *
 * This function behaves the same as <i>#ftell</i>.  The only
 * difference is that <i>#ftell</i> returns a value of type <b>long</b>.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle of file to get current position of
 *
 * \return    Current position in file, or -1L on failure.
 *
 * \sa        #fseek
 * \sa        #ftello
 * \sa        #fgetpos
 */
//---------------------------------------------------------------------------
off_t    ftello(FILE* f_handle);                                                 

/** 
 * \brief     Gets exclusive access to a file.
 *
 * Sleeps until exclusive access to a file is available.  Note that locks
 * cannot be nested.  A nested lock will be released on the very first call
 * to <i>#funlockfile</i>, and <b>not</b> the matching call.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle of file to acquire exclusive access for
 *
 * \sa        #ftrylockfile
 * \sa        #funlockfile
 */
//---------------------------------------------------------------------------
void     flockfile(FILE* f_handle);                                              

/**
 * \brief     Tries to get exclusive accress to a file.
 *
 * Obtains exclusive access to a file if it is available.  Otherwise, returns
 * without waiting for exclusive access.  Note that locks cannot be nested.
 * A nested lock will be released on the very first call to <i>#funlockfile</i>,
 * and <b>not</b> the matching call.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle to file we will try to get exclusive access to
 *
 * \return    0 if the file was locked, non-zero if someone else has the lock
 *
 * \sa        #flockfile
 * \sa        #funlockfile
 */
//---------------------------------------------------------------------------
int      ftrylockfile(FILE* f_handle);                                           

/**
 * \brief     Release exclusive access on a file.
 *
 * Releases exclusive access that was earlier acquired on this file
 * using <i>#flockfile</i> or <i>#ftrylockfile</i>.  Note that 
 * locks cannot be nested.  This function will release all locks that
 * the current thread/process have on the file.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle to file to release exclusive access for
 *
 * \sa        #flockfile
 * \sa        #ftrylockfile
 */
//---------------------------------------------------------------------------
void     funlockfile(FILE* f_handle);                                            

/**
 * \brief     Write a number of bytes to a file stream.
 *
 * Writes a block of data to a file stream.  This function allows you to 
 * write <i>num</i> elements of size <i>size</i>.  However, note that this 
 * function always behaves as if it had been called by:
 * <code><pre>
 *       fwrite(ptr, 1, size*num, f_handle);
 * </pre></code>
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     ptr       pointer to buffer of data to be written
 * \param     size      size of each element to be written
 * \param     num       number of elements to write
 * \param     f_handle  handle to file to write to
 *
 * \return    number of elements written
 *
 * \sa        #fputc
 * \sa        #fread
 */
//---------------------------------------------------------------------------
size_t   fwrite(const void* ptr, size_t size, size_t num, 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. 
 * Note: This function is equivalent to <i>#fgetc</i>. 
 *
 * 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        #fgetc 
 * \sa        #feof
 * \sa        #putc
 */
//---------------------------------------------------------------------------
int      getc(FILE* f_handle);                                                   

/**
 * \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.  Note: This function is equivalent
 * to <i>#fputc</i>.
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     value     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        #getc
 * \sa        #fputc
 */
//---------------------------------------------------------------------------
int      putc(int value, FILE* f_handle);                                        

/**
 * \brief     Removes a file from the file system.
 *
 * Deletes the file specified by <i>filename</i>.  
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     filename  file name that will be deleted
 *
 * \return    0 on success, non-zero on failure
 *
 * \sa        #rename
 */
//---------------------------------------------------------------------------
int      remove(const char* filename);                                           

/**
 * \brief     Renames a file.
 *
 * Renames the file identified by <i>oldname</i> to now be identified
 * by <i>newname</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     oldname  filename of the file that will change names
 * \param     newname  new name for the file called <i>oldname</i>
 *
 * \return    0 on success, non-zero on failure
 *
 * \sa        #remove
 */
//---------------------------------------------------------------------------
int      rename(const char* oldname, const char* newname);                       

/**
 * \brief     Resets the file position indicator for a stream.
 *
 * Sets the file position indicator for the stream to the beginning of the
 * file.  It also resets the end of file condition.  This is functionally 
 * equivalent to:
 * <code><pre>
 *     fseek(f_handle, 0, SEEK_SET);
 *     clearerr(f_handle);
 * </pre></code>
 *
 * This function is safe to be called from multiple processes at the same 
 * time.
 *
 * \param     f_handle  handle to file that the streams will be reset to the
 *                      beginning for
 *
 * \sa        #fseek
 * \sa        #fsetpos
 */
//---------------------------------------------------------------------------
void     rewind(FILE* f_handle);                                                 

/**
 * \brief     Generates a path/filename that can be used for a temporary file.
 *