Ignore:
Timestamp:
Feb 7, 2010, 1:22:38 AM (10 years ago)
Author:
Sam Hocevar
Message:

Document file functions and fix a few issues here and there.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • libcaca/trunk/caca/file.c

    r4148 r4318  
    5151#endif
    5252
     53/** \brief Open a file for reading or writing
     54 *
     55 *  Create a caca file handle for a file. If the file is zipped, it is
     56 *  decompressed on the fly.
     57 *
     58 *  If an error occurs, NULL is returned and \b errno is set accordingly:
     59 *  - \c ENOSTS Function not implemented.
     60 *  - \c EINVAL File not found or permission denied.
     61 *
     62 *  \param path The file path
     63 *  \param mode The file open mode
     64 *  \return A file handle to \e path.
     65 */
    5366caca_file_t *caca_file_open(char const *path, const char *mode)
    5467{
     
    6982    {
    7083        free(fp);
     84        seterrno(EINVAL);
    7185        return NULL;
    7286    }
     
    109123            free(fp);
    110124            gzclose(fp->gz);
     125            seterrno(EINVAL);
    111126            return NULL;
    112127        }
     
    118133    {
    119134        free(fp);
     135        seterrno(EINVAL);
    120136        return NULL;
    121137    }
     
    126142}
    127143
     144/** \brief Close a file handle
     145 *
     146 *  Close and destroy the resources associated with a caca file handle.
     147 *
     148 *  This function is a wrapper for fclose() or, if available, gzclose().
     149 *
     150 *  \param fp The file handle
     151 *  \return The return value of fclose() or gzclose().
     152 */
    128153int caca_file_close(caca_file_t *fp)
    129154{
     
    144169}
    145170
     171/** \brief Return the position in a file handle
     172 *
     173 *  Return the file handle position, in bytes.
     174 *
     175 *  \param fp The file handle
     176 *  \return The current offset in the file handle.
     177 */
    146178uint64_t caca_file_tell(caca_file_t *fp)
    147179{
     
    158190}
    159191
     192/** \brief Read data from a file handle
     193 *
     194 *  Read data from a file handle and copy them into the given buffer.
     195 *
     196 *  \param fp The file handle
     197 *  \param ptr The destination buffer
     198 *  \param size The number of bytes to read
     199 *  \return The number of bytes read
     200 */
    160201size_t caca_file_read(caca_file_t *fp, void *ptr, size_t size)
    161202{
     
    172213}
    173214
     215/** \brief Write data to a file handle
     216 *
     217 *  Write the contents of the given buffer to the file handle.
     218 *
     219 *  \param fp The file handle
     220 *  \param ptr The source buffer
     221 *  \param size The number of bytes to write
     222 *  \return The number of bytes written
     223 */
    174224size_t caca_file_write(caca_file_t *fp, const void *ptr, size_t size)
    175225{
     
    195245}
    196246
     247/** \brief Read a line from a file handle
     248 *
     249 *  Read one line of data from a file handle, up to one less than the given
     250 *  number of bytes. A trailing zero is appended to the data.
     251 *
     252 *  \param fp The file handle
     253 *  \param s The destination buffer
     254 *  \param size The maximum number of bytes to read
     255 *  \return The number of bytes read, including the trailing zero
     256 */
    197257char *caca_file_gets(caca_file_t *fp, char *s, int size)
    198258{
     
    229289}
    230290
     291/** \brief Tell whether a file handle reached end of file
     292 *
     293 *  Return the end-of-file status of the file handle.
     294 *
     295 *  This function is a wrapper for feof() or, if available, gzeof().
     296 *
     297 *  \param fp The file handle
     298 *  \return 1 if EOF was reached, 0 otherwise
     299 */
    231300int caca_file_eof(caca_file_t *fp)
    232301{
Note: See TracChangeset for help on using the changeset viewer.