/* fileutil.h PUBLIC DOMAIN 2010 tom.viza@gmail.com */

/*  I, Tom Vajzovic, am the author of this software and its documentation  */
/*  and permanently abandon all copyright and other intellectual property  */
/*  rights in them, including the right to be identified as the author.    */

/*  I am fairly certain that this software does what the documentation     */
/*  says it does, but I do not guarantee that it does, or that it does     */
/*  what you think it should.  I do not guarantee that it will not have    */
/*  undesirable side effects.                                              */

/*  You are free to use, modify and distribute this software as you        */
/*  please, but you do so at your own risk.  If you remove or hide this    */
/*  warning then you may be responsible for any problems that are          */
/*  encountered by those who obtain the software through you.              */

#ifndef FILEUTIL_H_INCLUDED
#define FILEUTIL_H_INCLUDED

#include <sys/types.h>

/****************************************************************************/
/*                                                                          */
/* These functions return a single datum from stat(2)                       */
/*                                                                          */
/****************************************************************************/
off_t  fd_filesize  ( int fd );
size_t fd_blocksize ( int fd );

/****************************************************************************/
/*                                                                          */
/* These functions set a single flag using fcntl(2)                         */
/*                                                                          */
/****************************************************************************/
int fd_blocking    ( int fd );
int fd_nonblocking ( int fd );
int fd_cloexec     ( int fd );

/****************************************************************************/
/*                                                                          */
/* These functions make the file previously available on descriptor /oldfd/ */
/* available on the descriptor /newfd/.  Those containing /move/ also make  */
/* it no longer available on /oldfd/.                                       */
/*                                                                          */
/* Those prefixed /safe/ fail if any file is already open on /newfd/.       */
/* Those prefixed /close/ call close(2) on /newfd/ first, and fail if it    */
/* does, including if no file was open there.  Those with no prefix call    */
/* close(2) and fail if it does, apart from if no file was open there.      */
/* Those prefixed discard will close any file on /newfd/ but not fail if    */
/* there is a problem doing that.                                           */
/*                                                                          */
/* These functions do nothing and return success if /oldfd/ equals /newfd/. */
/*                                                                          */
/* These functions return zero on success, non-zero on error.               */
/*                                                                          */
/****************************************************************************/
int discard_copy_fd( int newfd, int oldfd );
int   close_copy_fd( int newfd, int oldfd );
int         copy_fd( int newfd, int oldfd );
int    safe_copy_fd( int newfd, int oldfd );
int discard_move_fd( int newfd, int oldfd );
int   close_move_fd( int newfd, int oldfd );
int         move_fd( int newfd, int oldfd );
int    safe_move_fd( int newfd, int oldfd );

/****************************************************************************/
/*                                                                          */
/* These functions take the same arguments as read or write.                */
/* Those returning ssize_t return the same as read or write.                */
/* Those returning int return zero on success or non-zero on failure.       */
/*                                                                          */
/* These functions call read or write repeatedly until it returns zero      */
/* (end of file) or less than zero (error) or until the full number of      */
/* bytes has been transfered.                                               */
/*                                                                          */
/* If read or write fail with errno set to EINTR they repeat the call.      */
/*                                                                          */
/* If read or write fail with EAGAIN or EWOULDBLOCK they set the file       */
/* descriptor to blocking if it is not already (if they do this and they    */
/* are not going to close the file then they restore the flags before       */
/* returning).                                                              */
/*                                                                          */
/* On any other error they close the file descriptor and set errno          */
/* according to the first error encountered.  Those containing close also   */
/* close the file on success, and fail if close fails.                      */
/*                                                                          */
/* Those containing all fail setting errno to EAGAIN if any less than the   */
/* full number of bytes are transfered.                                     */
/*                                                                          */
/****************************************************************************/
ssize_t  read_blocking        ( int fd,       void *buf, size_t max );
ssize_t  write_blocking       ( int fd, const void *buf, size_t max );
int      read_all             ( int fd,       void *buf, size_t max );
int      write_all            ( int fd, const void *buf, size_t max );
ssize_t  read_blocking_close  ( int fd,       void *buf, size_t max );
ssize_t  write_blocking_close ( int fd, const void *buf, size_t max );
int      read_all_close       ( int fd,       void *buf, size_t max );
int      write_all_close      ( int fd, const void *buf, size_t max );

#endif /* FILEUTIL_H_INCLUDED */