fclear

Purpose

     Makes a hole in a file.

Syntax

     long fclear (fildes, nbytes)
     int fildes;
     unsigned long nbytes;

Description

     The fclear system call zeroes  the number of bytes speci-
     fied  by the  nbytes  parameter starting  at the  current
     position of the file open  on file descriptor fildes.  If
     Distributed Services  is installed  on your  system, this
     file can  reside on another node.   This function differs
     from the logically equivalent  write operation in that it
     returns full blocks  of binary zeros to  the file system,
     constructing holes in the file.   The seek pointer of the
     file is advanced by nbytes.

     If you  fclear past the  end of a  file, the rest  of the
     file  is cleared  and  the seek  pointer  is advanced  by
     nbytes.  The  file size  is updated  to include  this new
     hole, which leaves the current  file position at the byte
     immediately beyond the new end-of-file.

Return Value

     Upon  successful   completion,  a  value  of   nbytes  is
     returned.  If the fclear system call fails, a value of -1
     is returned and errno is set to indicate the error.

Diagnostics

     The fclear system  call fails if one or more  of the fol-
     lowing are true:

     EIO        I/O error.

     EBADF      The  fildes   option  is  not  a   valid  file
                descriptor open for writing.

     EINVAL     The  file is  a  FIFO,  directory, or  special
                file.

     EMFILE     The  file is  mapped copy-on-write  by one  or
                more processes.

     EAGAIN     The write  operation in fclear failed,  due to
                an enforced write lock on the file.

     If  Distributed Services  is  installed  on your  system,
     fclear can also fail if one  or more of the following are
     true:

     EDIST         The   server   has  blocked   new   inbound
                   requests.

     EDIST         Outbound requests are currently blocked.

     ENOMEM        Either  this node  or the  server does  not
                   have enough memory available to service the
                   request.

     EBADCONNECT   An attempt to use  an existing network con-
                   nection with a remote node failed.

Related Information

     In this book:  "ftruncate."