close()--Close File or Socket Descriptor
Syntax
#include <unistd.h> int close(int fildes);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The close() function closes a descriptor, fildes. This frees the descriptor to be returned by future open() calls and other calls that create descriptors.
When the last open descriptor for a file is closed, the file itself is closed. If the link count of the file is zero at that time, the space occupied by the file is freed and the file becomes inaccessible.
close() unlocks (removes) all outstanding byte locks that a job has on the associated file.
When all file descriptors associated with a pipe or FIFO special file are closed, any data remaining in the pipe or FIFO is discarded and internal storage used is returned to the system.
When fildes refers to a socket, close() closes the socket identified by the descriptor.
For information about the exit point that can be associated with close(), see Integrated File System Scan on Close Exit Programs.
Parameters
- fildes
- (Input) The descriptor to be closed.
Authorities
No authorization is required. Authorization is verified during open(), creat(), or socket().
Return Value
0 | close() was successful. |
-1 | close() was not successful. The errno global variable is set to indicate the error. |
Error Conditions
If close() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Error condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. |
[EAGAIN] | |
[EBADF] | |
[EBADFID] | |
[EBUSY] | |
[EDAMAGE] | |
[EDEADLK] | |
[EINTR] | |
[EINVAL] | |
[EIO] | |
[EJRNDAMAGE] | |
[EJRNENTTOOLONG] | |
[EJRNINACTIVE] | |
[EJRNRCVSPC] | |
[ENEWJRN] | |
[ENEWJRNRCV] | |
[ENOBUFS] | |
[ENOSPC] | |
[ENOSYS] | |
[ENOTAVAIL] | |
[ENOTSAFE] | |
[ESCANFAILURE] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
Additionally, if interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
CPFA081 E | Unable to set return value or error code. |
CPFA0D4 E | File system error occurred. Error number &1. |
Usage Notes
- This function will fail with
error code [EBADF] when fildes is a scan descriptor that was passed to
one of the scan-related exit programs. See Integrated
File System Scan on Open Exit Programs and
Integrated File System Scan on Close Exit Programs for more information.
- 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
- When a socket descriptor is closed, the system tries to send any queued
data associated with the socket.
- For AF_INET sockets, depending on
whether the SO_LINGER socket option is set, queued data may be
discarded.
Note: For these sockets, the default value for the SO_LINGER socket option has the option flag set off (the system attempts to send any queued data with an infinite wait time).
- For AF_INET sockets, depending on
whether the SO_LINGER socket option is set, queued data may be
discarded.
- A socket descriptor being shared among multiple processes is not closed until the process that issued the close() is the last process with access to the socket.
Related Information
- The <unistd.h> file (see Header Files for UNIX®-Type Functions)
- creat()--Create or Rewrite File
- dup()--Duplicate Open File Descriptor
- dup2()--Duplicate Open File Descriptor to Another Descriptor
- fcntl()--Perform File Control Command
- Integrated File System Scan on Close Exit Programs
- open()--Open File
- setsockopt()--Set Socket Options
- unlink()--Remove Link to File
Example
The following example uses close().
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <stdio.h> #include <fcntl.h> #include <unistd.h> main() { int fd1, fd2; char out[20]="Test string", fn[]="test.file", in[20]; short write_error; memset(in, 0x00, sizeof(in)); write_error = 0; if ( (fd1 = creat(fn,S_IRWXU)) == -1) perror("creat() error"); else if ( (fd2 = open(fn,O_RDWR)) == -1) perror("open() error"); else { if (write(fd1, out, strlen(out)+1) == -1) { perror("write() error"); write_error = 1; } close(fd1); if (!write_error) { if (read(fd2, in, sizeof(in)) == -1) perror("read() error"); else printf("string read from file was: '%s'\n", in); } close(fd2); } }
Output:
string read from file was: 'Test string'
API introduced: V3R1