Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
FSPACECTL(2)		       System Calls Manual		    FSPACECTL(2)

NAME
     fspacectl -- space management in a file

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <fcntl.h>

     int
     fspacectl(int fd, int cmd, const struct spacectl_range *rqsr, int flags,
	 struct spacectl_range *rmsr);

DESCRIPTION
     fspacectl is a system call performing space management over a file.  The fd
     argument  specifies  the file descriptor to be operated on by the cmd argu-
     ment.  The rqsr argument points to a spacectl_range structure that contains
     the requested operation range.  The flags argument controls the behavior of
     the operation to take  place.   If  the  rmsr  argument  is  non-NULL,  the
     spacectl_range structure it points to is updated to contain the unprocessed
     operation range after the system call returns.

     For  a  successful  completion without an unprocessed part in the requested
     operation	range,	rmsr->r_len  is  updated  to  be  the	value	0,   and
     rmsr->r_offset is updated to be rqsr->r_offset plus the number of bytes ze-
     roed before the end-of-file.  The file descriptor's file offset is not used
     or  modified by the system call.  Both rqsr and rmsr arguments can point to
     the same structure.

     The spacectl_range structure is defined as:

     struct spacectl_range {
	     off_t r_offset;
	     off_t r_len;
     };

     The operation specified by the cmd argument may be one of:

     SPACECTL_DEALLOC  Zero a region in the file specified by the rqsr argument.
		       The rqsr->r_offset has to be  a	value  greater	than  or
		       equal to 0, and the rqsr->r_len has to be a value greater
		       than 0.

		       If  the	file  system supports hole-punching, file system
		       space deallocation may be performed in the given region.

     The flags argument needs to be the value 0 currently.

RETURN VALUES
     Upon successful completion, the value 0 is returned; otherwise the value -1
     is returned and errno is set to indicate the error.

ERRORS
     Possible failure conditions:

     [EBADF]		The fd argument is not a valid file descriptor.

     [EBADF]		The fd argument references a file that was opened  with-
			out write permission.

     [EINTR]		A signal was caught during execution.

     [EINVAL]		The cmd argument is not valid.

     [EINVAL]		If  the  cmd  argument	is  SPACECTL_DEALLOC, either the
			rqsr->r_offset argument  was  less  than  zero,  or  the
			rqsr->r_len argument was less than or equal to zero.

     [EINVAL]		The  value  of	rqsr->r_offset	+ rqsr->r_len is greater
			than OFF_MAX.

     [EINVAL]		An invalid or unsupported flag is included in flags.

     [EINVAL]		A flag included in flags is not supported by the  opera-
			tion specified by the cmd argument.

     [EFAULT]		The  rqsr  or a non-NULL rmsr argument point outside the
			process' allocated address space.

     [EIO]		An I/O error occurred while reading from or writing to a
			file system.

     [EINTEGRITY]	Corrupted data was detected while reading from the  file
			system.

     [ENODEV]		The  fd  argument does not refer to a file that supports
			fspacectl.

     [ENOSPC]		There is insufficient free space remaining on  the  file
			system storage media.

     [ENOTCAPABLE]	The file descriptor fd has insufficient rights.

     [ESPIPE]		The fd argument is associated with a pipe or FIFO.

SEE ALSO
     creat(2), ftruncate(2), open(2), unlink(2)

HISTORY
     The fspacectl system call appeared in FreeBSD 14.0.

AUTHORS
     fspacectl	and this manual page were written by Ka Ho Ng <khng@FreeBSD.org>
     under sponsorship from the FreeBSD Foundation.

FreeBSD ports 15.quarterly	 August 25, 2021		    FSPACECTL(2)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fspacectl&sektion=2&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help