close Subroutine

Purpose

Closes a file descriptor.

Syntax

#include <unistd.h>

Description

The close subroutine closes the file or shared memory object associated with the FileDescriptor parameter. If Network File System (NFS) is installed on your system, this file can reside on another node.

All file regions associated with the file specified by the FileDescriptor parameter that this process has previously locked with the lockf or fcntl subroutine are unlocked. This occurs even if the process still has the file open by another file descriptor.

If the FileDescriptor parameter resulted from an open subroutine that specified O_DEFER, and this was the last file descriptor, all changes made to the file since the last fsync subroutine are discarded.

If the FileDescriptor parameter is associated with a mapped file, it is unmapped. The shmat subroutine provides more information about mapped files.

The close subroutine attempts to cancel outstanding asynchronous I/O requests on this file descriptor. If the asynchronous I/O requests cannot be canceled, the application is blocked until the requests have completed.

If the FileDescriptor parameter is associated with a shared memory object and the shared memory object remains referenced at the last close (that is, a process has it mapped), the entire contents of the memory object persists until the memory object becomes unreferenced. If this is the last close of a shared memory object and the close results in the memory object becoming unreferenced, and the memory object has been unlinked, the memory object is removed. The shm_open subroutine provides more information about shared memory objects.

The close subroutine is blocked until all subroutines which use the file descriptor return to usr space. For example, when a thread is calling close and another thread is calling select with the same file descriptor, the close subroutine does not return until the select call returns.

When all file descriptors associated with a pipe or FIFO special file have been closed, any data remaining in the pipe or FIFO is discarded. If the link count of the file is 0 when all file descriptors associated with the file have been closed, the space occupied by the file is freed, and the file is no longer accessible.

Parameters

Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to identify the error.

The underlying file system implementation might report any one of the values from the /usr/include/errno.h file to the close subroutine. The close subroutine returns a value of -1 and the errno global variable is set to the return value from the file system, but the file is still closed. The state of the FileDescriptor parameter is closed except for the conditions specified in the Error Codes section.

Error Codes

The close subroutine is unsuccessful if the following is true:

The close subroutine may also be unsuccessful if the file being closed is NFS-mounted and the server is down under the following conditions:

• The file is on a hard mount.
• The file is locked in any manner.

The close subroutine may also be unsuccessful if NFS is installed and the following is true: