ltrunc()

truncate a file at a given position

Synopsis:

#include <sys/types.h>
#include <unistd.h>
off_t ltrunc( int fildes, 
              off_t offset,
              int whence );

Description:

The ltrunc() function attempts to truncate the file at a specified position. The file, referenced by the open file descriptor fildes, must have been opened O_WRONLY or O_RDWR. The truncation point is calculated using the value of offset as a relative offset from a file position determined by the value of the argument whence. The value of offset may be negative, although a negative truncation point (one before the beginning of the file) is an error.

The ltrunc() function ignores advisory locks that may have been set by the fcntl(), lock() or locking() functions.

The truncation point is determined based upon the value of whence, which may have one of three possible values as defined in <unistd.h>, as follows:

SEEK_SET

The truncation point is set to offset.

SEEK_CUR

The truncation point is set to the current file position plus offset.

SEEK_END

The truncation point is set to the size of the file plus offset.

The calculated truncation point, if within the existing bounds of the file, determines the new file size; all data after the truncation point no longer exists. If the truncation point is past the existing end of file, the file size is not changed. An error occurs if you attempt to truncate before the beginning of the file (that is, a negative truncation point).

The current seek position is not changed by this function under any circumstance, including the case where the current seek position is beyond the truncation point.

Returns:

The new file size. If a truncation point beyond the existing end of file was specified, the existing file size is returned, and the file size remains unchanged. Otherwise, ltrunc() returns -1 and sets errno to indicate the error. The file size remains unchanged in the event of an error.

Errors:

EBADF

The fildes argument is not a valid file descriptor, open for writing.

EINVAL

The whence argument is not a proper value, or the resulting file size would be invalid.

ENOSYS

An attempt was made to truncate a file of a type that does not support truncation (for example, a file associated with the device manager).

ESPIPE

The fildes argument is associated with a pipe or FIFO.

Examples:

#include <stdio.h>
#include <fcntl.h>
#include <sys/types.h>
#include <unistd.h>

char buffer[1000];

void main()
  {
    int fd, stat;

    fd = open( "test", O_CREAT | O_RDWR, 0666 );
    if( fd == -1 ) {
      fprintf( stderr, "Open error\n" );
      exit( -1 );
    }
    /* Create a 1000 byte file */
    write( fd, buffer, 1000 );

    /* Seek back to offset 500 and truncate the file */
    if( ltrunc( fd, 500, SEEK_SET ) == -1 ) {
      fprintf( stderr, "ltrunc error\n" );
      exit( -1 );
    }
    close( fd );
    fd = open( "test", O_CREAT | O_RDWR, 0666 );
    printf( "File size = %ld\n",
      lseek( fd, 0, SEEK_END ) );
    close( fd );
  }

Classification:

QNX

See also:

errno, lseek()