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

FreeBSD Manual Pages


home | help
close(2)							      close(2)

       close - close a file descriptor

       #include	<unistd.h>

       int close(int fildes);

       The  close()  function  deallocates  the	 file  descriptor indicated by
       fildes. To deallocate means to make the file descriptor	available  for
       return  by subsequent calls to open(2) or other functions that allocate
       file descriptors. All outstanding record	locks owned by the process  on
       the  file associated with the file descriptor will be removed (that is,

       If close() is interrupted by a signal that is to	be caught, it will re-
       turn -1 with errno set to EINTR and the state of	fildes is unspecified.
       If an I/O error occurred	while reading from or writing to the file sys-
       tem  during close(), it returns -1, sets	errno to EIO, and the state of
       fildes is unspecified.

       When all	file descriptors associated with a pipe	or FIFO	 special  file
       are closed, any data remaining in the pipe or FIFO will be discarded.

       When all	file descriptors associated with an open file description have
       been closed the open file description will be freed.

       If the link count of the	file is	0, when	all file  descriptors  associ-
       ated  with  the file are	closed,	the space occupied by the file will be
       freed and the file will no longer be accessible.

       If a STREAMS-based (see intro(2)) fildes	 is  closed  and  the  calling
       process was previously registered to receive a SIGPOLL signal (see sig-
       nal(3C))	for events  associated	with  that  STREAM  (see  I_SETSIG  in
       streamio(7I)),  the calling process will	be unregistered	for events as-
       sociated	with the STREAM.  The last close() for	a  STREAM  causes  the
       STREAM  associated  with	 fildes	 to  be	 dismantled. If	O_NONBLOCK and
       O_NDELAY	are not	set and	there have been	 no  signals  posted  for  the
       STREAM, and if there is data on the module's write queue, close() waits
       up to 15	seconds	(for each module and driver) for any output  to	 drain
       before  dismantling  the	 STREAM.  The time delay can be	changed	via an
       I_SETCLTIME ioctl(2) request (see streamio(7I)).	If the	O_NONBLOCK  or
       O_NDELAY	flag is	set, or	if there are any pending signals, close() does
       not wait	for output to drain, and dismantles the	STREAM immediately.

       If fildes is associated with one	end of a pipe, the last	close()	causes
       a  hangup  to  occur on the other end of	the pipe.  In addition,	if the
       other end of the	pipe has been named  by	 fattach(3C),  then  the  last
       close()	forces	the  named  end	to be detached by fdetach(3C).	If the
       named end has no	open file descriptors associated with it and gets  de-
       tached, the STREAM associated with that end is also dismantled.

       If fildes refers	to the master side of a	pseudo-terminal, a SIGHUP sig-
       nal is sent to the session leader, if any, for which the	slave side  of
       the  pseudo-terminal  is	 the  controlling  terminal. It	is unspecified
       whether closing the master side	of  the	 pseudo-terminal  flushes  all
       queued input and	output.

       If  fildes refers to the	slave side of a	STREAMS-based pseudo-terminal,
       a zero-length message may be sent to the	master.

       When there is an	 outstanding  cancelable  asynchronous	I/O  operation
       against	fildes when close() is called, that I/O	operation is canceled.
       An I/O operation	that is	not canceled completes as if the close() oper-
       ation  had not yet occurred.  All operations that are not canceled will
       complete	as if the close() blocked until	the operations completed.

       If a shared memory object or a memory mapped file remains referenced at
       the last	close (that is,	a process has it mapped), then the entire con-
       tents of	the memory object will persist until the memory	object becomes
       unreferenced.  If this is the last close	of a shared memory object or a
       memory mapped file and the close	results	in the memory object  becoming
       unreferenced,  and the memory object has	been unlinked, then the	memory
       object will be removed.

       If fildes refers	to a socket, close()  causes  the  socket  to  be  de-
       stroyed.	 If the	socket is connection-mode, and the SO_LINGER option is
       set for the socket with non-zero	linger time, and the  socket  has  un-
       transmitted  data, then close() will block for up to the	current	linger
       interval	until all data is transmitted.

       Upon successful completion, 0 is	returned. Otherwise,  -1  is  returned
       and errno is set	to indicate the	error.

       The close() function will fail if:

       EBADF	       The fildes argument is not a valid file descriptor.

       EINTR	       The close() function was	interrupted by a signal.

       ENOLINK	       The fildes argument is on a remote machine and the link
		       to that machine is no longer active.

       ENOSPC	       There was no free space remaining on  the  device  con-
		       taining the file.

       The close() function may	fail if:

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

       Example 1: Reassign a file descriptor.

       The following example closes the	file descriptor	associated with	 stan-
       dard  output  for  the current process, re-assigns standard output to a
       new file	descriptor, and	closes the original file descriptor  to	 clean
       up.  This  example assumes that the file	descriptor 0, which is the de-
       scriptor	for standard input, is not closed.

       #include	<unistd.h>
       int pfd;

       Incidentally, this is exactly what could	be achieved using:

       dup2(pfd, 1);

       Example 2: Close	a file descriptor.

       In the following	example, close() is used to close  a  file  descriptor
       after an	unsuccessful attempt is	made to	associate that file descriptor
       with a stream.

       #include	<stdio.h>
       #include	<unistd.h>
       #include	<stdlib.h>

       #define LOCKFILE	"/etc/ptmp"
       int pfd;
       FILE *fpfd;
       if ((fpfd = fdopen (pfd,	"w")) == NULL) {

       An application that used	the stdio function fopen(3C) to	 open  a  file
       should use the corresponding fclose(3C) function	rather than close().

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |Async-Signal-Safe		   |

       intro(2),   creat(2),  dup(2),  exec(2),	 fcntl(2),  ioctl(2),  open(2)
       pipe(2),	fattach(3C), fclose(3C), fdetach(3C),  fopen(3C),  signal(3C),
       signal.h(3HEAD),	attributes(5), standards(5), streamio(7I)

				  18 Oct 2005			      close(2)


Want to link to this manual page? Use this URL:

home | help