close()--Close File or Socket Descriptor

#include <unistd.h>

int close(int fildes);


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 fildes refers to a socket, close() closes the socket identified by the descriptor.

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.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

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]

Operation would have caused the process to be suspended.

[EBADF]

Descriptor not valid.

A file descriptor argument was out of range, referred to a file that was not open, or a read or write request was made to a file that is not open for that operation.

A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is incorrect, or does not refer to an open file.

[EBADFID]

A file ID could not be assigned when linking an object to a directory.

The file ID table is missing or damaged.

To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible.

[EBUSY]

Resource busy.

An attempt was made to use a system resource that is not available at this time.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

[EINTR]

Interrupted function call.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOSPC]

No space available.

The requested operations required additional space on the device and there is no space left. This could also be caused by exceeding the user profile storage limit when creating or transferring ownership of an object.

Insufficient space remains to hold the intended file, directory, or link.

[ENOSYS]

Function not implemented.

An attempt was made to use a function that is not available in this implementation for any object or any arguments.

The path name given refers to an object that does not support this function.

[ENOTSAFE]

Function is not allowed in a job that is running with multiple threads.

[ESTALE]

File or object handle rejected by server.

If you are accessing a remote file through the Network File System, the file may have been deleted at the server.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

[EADDRNOTAVAIL]

Address not available.

[ECONNABORTED]

Connection ended abnormally.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

[ECONNRESET]

A connection with a remote socket was reset by that socket.

[EHOSTDOWN]

A remote host is not available.

[EHOSTUNREACH]

A route to the remote host is not available.

[ENETDOWN]

The network is not currently available.

[ENETRESET]

A socket is connected to a host that is no longer available.

[ENETUNREACH]

Cannot reach the destination network.

[ESTALE]

File or object handle rejected by server.

If you are accessing a remote file through the Network File System, the file may have been deleted at the server.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Error Messages

The following messages may be sent from this function:

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.

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:

   • There are secondary threads active 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

     • QOPT

     • QLANSrv

2. When a socket descriptor is closed, the system tries to send any queued data associated with the socket.

   • For AF_NS or 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_TELEPHONY sockets, depending on whether the SO_LINGER socket option is set, buffered data may be discarded.

     Note: For these sockets, the default value for the SO_LINGER socket option has the option flag set on with a time value of 1 second (the system will wait up to 1 second to send buffered data before clearing the telephone connection).

3. 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

• open()--Open File

• unlink()--Remove Link to File

Example

The following example uses close()

#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'