ioctl()--Perform File I/O Control Request

#include <sys/types.h>
#include <sys/ioctl.h>

int ioctl
  (int file_descriptor, unsigned long req, ...);

Threadsafe: Conditional; see Usage Notes.

The ioctl() function performs control functions (requests) on a file descriptor.

Parameters

file_descriptor

(Input) The descriptor on which the control request is to be performed.

req

(Input) The control request to be performed.

...

(Input) A variable number of optional parameters, dependent on the request.

The control request can be as follows:

FIONREAD

Return the number of bytes available to be read. The third parameter represents a pointer to an integer that will be set to the number of bytes available to be read.

For information on additional control functions supported by sockets, see ioctl() in the Socket Programming information.

Authorities

No authorization is required.

Return Value

0

ioctl() was successful.

-1

ioctl() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If ioctl() 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.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[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. Either the requested function is not supported, or the optional parameter is not valid.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

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

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

[EUNATCH]

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

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

CPFA0D4 E

File system error occurred.

CPF3CF2 E

Error(s) occurred during running of &1 API.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

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. QDLS File System Differences

   QDLS does not support ioctl().

3. QOPT File System Differences

   QOPT does not support ioctl().

Related Information

• The <sys/ioctl.h> file (see Header Files for UNIX-Type Functions)

• The <sys/types.h> file (see Header Files for UNIX-Type Functions)

• The ioctl()--Change Descriptor Attributes API