close Subroutine

Purpose

Closes a file descriptor.

Syntax

#include <unistd.h>

int close (
FileDescriptor)
int FileDescriptor;

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 (open, openat, openx, openxat, open64, open64at, open64x, open64xat, creat, or creat64 Subroutine) 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.

Note: If the FileDescriptor parameter refers to a device and the close subroutine actually results in a device close, and the device close routine returns an error, the error is returned to the application. However, the FileDescriptor parameter is considered closed and it may not be used in any subsequent calls.

All open file descriptors are closed when a process exits. In addition, file descriptors may be closed during the exec subroutine if the close-on-exec flag has been set for that file descriptor.

Parameters

Item Description
FileDescriptor Specifies a valid open file descriptor.

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:

Item Description
EBADF The FileDescriptor parameter does not specify a valid open file descriptor.

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 close subroutine may also be unsuccessful if NFS is installed and the following is true:

Item Description
ETIMEDOUT The connection timed out.
The success of the close subroutine is undetermined if the following is true:
Item Description
EINTR The state of the FileDescriptor is undetermined. Retry the close routine to ensure that the FileDescriptor is closed.