ftruncate()--Truncate File

 #include <unistd.h>

 int ftruncate(int file_descriptor, off_t length);  

The ftruncate() function truncates the file indicated by the open file descriptor file_descriptor to the indicated length. file_descriptor must be a "regular file" that is open for writing. (A regular file is a stream file that can support positioning the file offset.) If the file size exceeds length, any extra data is discarded. If the file size is smaller than length, the file is extended and filled with binary zeros to the indicated length. (In the QSYS.LIB and independent ASP QSYS.LIB file systems blanks are used instead of zeros to pad records after a member is extended.) The ftruncate() function does not modify the current file offset for any open file descriptions associated with the file.

If ftruncate() completes successfully, it marks the change time and modification times of the file. Also, the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits of the file mode are cleared. If ftruncate() is not successful, the file is unchanged.

If ftruncate() is used to truncate the file to 0 bytes and the file has a digital signature, the signature is deleted.

Parameters

file_descriptor

(Input) The file descriptor of the file.

length

(Input) The desired size of the file in bytes.

Authorities

No authorization is required. Authorization is verified during open() or creat().

Return Value

0

ftruncate() was successful.

-1

ftruncate() was not successful. The errno global variable is set to indicate the error. If the file descriptor is not open for writing, ftruncate returns a [EBADF] error. If the file descriptor is a valid descriptor open for writing but is not a descriptor for a regular file, ftruncate() returns a [EINVAL] error.

Error Conditions

If ftruncate() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could also indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • Where multiple threads exist in the job.
     
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
   
2. When you develop in C-based languages and this function is compiled with _LARGE_FILES defined, it will be mapped to ftruncate64(). Note also that the type of the length parameter will be remapped from off_t to off64_t.
   
   
3. For the Network File System, this function will fail with the [EFBIG] or the [EIO] error if the length specified is greater than the largest file size supported by the server.
   
   
4. Using this function on a character special file results in a return value of -1 and the errno global value set to [EINVAL].
   
   
5. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   This function is not supported for save files and members in certain types of physical files. Those attempts will fail with error code [ENOTSUP]. There may be messages listed in the job log that provide additional information about the reason for this failure.

6. If the request exceeds the process soft file size limit, signal SIFXFSZ is issued.

Related Information

• The <unistd.h> file (see Header Files for UNIX^®-Type Functions)
  
• ftruncate64()--Truncate File (Large File Enabled)
  
• open()--Open File

Example

The following example uses ftruncate().

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

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

#define string_len 1000

main() {
  char *mega_string;
  int  file_descriptor;
  int  ret;
  char fn[]="write.file";
  struct stat st;

  if ((mega_string = (char*) malloc(string_len)) == NULL)
    perror("malloc() error");
  else if ((file_descriptor = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    memset(mega_string, '0', string_len);
    if ((ret = write(file_descriptor, mega_string, string_len)) == -1)
      perror("write() error");
    else {
      printf("write() wrote %d bytes\n", ret);
      fstat(file_descriptor, &st);
      printf("the file has %ld bytes\n", (long) st.st_size);
      if (ftruncate(file_descriptor, 1) != 0)
        perror("ftruncate() error");
      else {
        fstat(file_descriptor, &st);
        printf("the file has %ld bytes\n", (long) st.st_size);
      }
    }
    close(file_descriptor);
    unlink(fn);
  }
  free(mega_string);
}

Output:

write() wrote 1000 bytes
the file has 1000 bytes
the file has 1 bytes

[ Back to top | UNIX-Type APIs | APIs by category ]