read()--Read from Descriptor

Syntax

#include <unistd.h>

ssize_t read(int file_descriptor,
             void *buf, size_t nbyte);

Threadsafe: Conditional; see Usage Notes.

From the file or socket indicated by file_descriptor, the read() function reads nbyte bytes of input into the memory area indicated by buf. If nbyte is zero, read() returns a value of zero without attempting any other action.

If file_descriptor refers to a "regular file" (a stream file that can support positioning the file offset) or any other type of file on which the job can do an lseek() operation, read() begins reading at the file offset associated with file_descriptor. A successful read() changes the file offset by the number of bytes read.

If read() is successful and nbyte is greater than zero, the access time for the file is updated.

read() is not supported for directories.

If file_descriptor refers to a descriptor obtained using the open() function with O_TEXTDATA specified, the data is read from the file assuming it is in textual form. The data is converted from the code page of the file to the code page of the application, job, or system as follows:

When reading from a true stream file, any line-formatting characters (such as carriage return, tab, and end-of-file) are just converted from one code page to another.
When reading from record files that are being used as stream files, end-of-line characters are added to the end of the data in each record.

If O_TEXTDATA was not specified on the open(), the data is read from the file without conversion. The application is responsible for handling the data.

In the QSYS.LIB file system, most end-of-file characters are symbolic; that is, they are stored outside the member. When reading:

If O_TEXTDATA is specified, both symbolic and nonsymbolic end-of-file characters can be seen.
If O_TEXTDATA is not specified (binary mode), only nonsymbolic end-of-file characters can be seen.

See the Usage Notes for write()--Write to Descriptor.

When file_descriptor refers to a socket, the read() function reads from the socket identified by the socket descriptor.

Parameters

file_descriptor: (Input) The descriptor to be read.
buf: (Output) A pointer to a buffer in which the bytes read are placed.
nbyte: (Input) The number of bytes to be read.

Authorities

No authorization is required.

Return Value

value: read() was successful. The value returned is the number of bytes actually read and placed in buf. This number is less than or equal to nbyte. It is less than nbyte only if read() reached the end of the file before reading the requested number of bytes. If read() is reading a regular file and encounters a part of the file that has not been written (but before the end of the file), read() places bytes containing zeros into buf in place of the unwritten bytes.
-1: read() was not successful. The errno global variable is set to indicate the error. If the value of nbyte is greater than SSIZE_MAX, read() sets errno to [EINVAL].

Error Conditions

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

This may occur if file_descriptor refers to a socket and the socket is using a connection-oriented transport service, and a connect() was previously completed. The thread, however, does not have the appropriate privileges to the objects that were needed to establish a connection. For example, the connect() required the use of an APPC device that the thread was not authorized to.

[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. Or, this read request was made to a file that was only open for writing.

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

This may occur if file_descriptor refers to a socket that is using a connectionless transport service, is not a socket of type SOCK_RAW, and is not bound to an address.

The file resides in a file system that does not support large files, and the starting offset of the file exceeds 2GB minus 2 bytes.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

There is not enough memory to perform the requested function.

[ENOTSAFE]

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

[EOVERFLOW]

Object is too large to process.

The object's data size exceeds the limit allowed by this function.

The file is a regular file, nbyte is greater than 0, the starting offset is before the end-of-file, and the starting offset is greater than or equal to 2GB minus 2 bytes.

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

When the descriptor refers to a socket, errno could indicate one of the following errors:

[ECONNABORTED]

Connection ended abnormally.

This error code indicates that the transport provider ended the connection abnormally because of one of the following:

The retransmission limit has been reached for data that was being sent on the socket.
A protocol error was detected.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

[ECONNRESET]

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

[EINTR]

Interrupted function call.

[ENOTCONN]

Requested operation requires a connection.

This error code is returned only on sockets that use a connection-oriented transport service.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

A non-blocking connect() was previously completed that resulted in the connection timing out. No connection is established. This error code is returned only on sockets that use a connection-oriented transport service.

[EUNATCH]

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

[EWOULDBLOCK]

Operation would have caused the process to be suspended.

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

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
QSYS.LIB File System Differences
The file access time for a database member is updated using the normal rules that apply to database files. At most, the access time is updated once per day.
If you previously used the integrated file system interface to manipulate a member that contains an end-of-file character, you should avoid using other interfaces (such as the Source Entry Utility or database reads and writes) to manipulate the member. If you use other interfaces after using the integrated file system interface, the end-of-file information will be lost.
QOPT File System Differences
The file access time is not updated on a read() operation.
Network File System Differences
Local access to remote files through the Network File System may produce unexpected results due to conditions at the server. Once a file is open, subsequent requests to perform operations on the file can fail because file attributes are checked at the server on each request. If permissions on the file are made more restrictive at the server or the file is unlinked or made unavailable by the server for another client, your operation on an open file descriptor will fail when the local Network File System receives these updates. The local Network File System also impacts operations that retrieve file attributes. Recent changes at the server may not be available at your client yet, and old values may be returned from operations. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.)
Reading and writing to files with the Network File System relies on byte-range locking to guarantee data integrity. To prevent data inconsistency, use the fcntl() API to get and release these locks.
QFileSvr.400 File System Differences
The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will be received.
For sockets that use a connection-oriented transport service (for example, sockets with a type of SOCK_STREAM), a return value of zero indicates one of the following:
- The partner program has issued a close() for the socket.
- The partner program has issued a shutdown() to disable writing to the socket.
- The connection is broken and the error was returned on a previously issued socket function.
- A shutdown() to disable reading was previously done on the socket.
For sockets that have a type of SOCK_SEQPACKET, each output operation by the partner program constitutes one record. If the record length is larger than the value specified by the nbyte parameter, the remaining data from the record is discarded.
The following applies to sockets that use a connectionless transport service (for example, a socket with a type of SOCK_DGRAM).
- If a connect() has been issued previously, then data can be received only from the address specified in the previous connect().
- The address from which data is received is discarded, since the read() has no address parameter.
- The entire message must be read in a single read operation. If the size of the message is too large to fit in the user supplied buffer, the remaining bytes of the message are discarded.
- A returned value of zero indicates one of the following:
  - The partner program has sent a NULL message (a datagram with no user data).
  - A shutdown() to disable reading was previously done on the socket.
  - The buffer length specified was zero.
For file systems that do not support large files, read() will return [EINVAL] if the starting offset exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that do support large files, read() will return [EOVERFLOW] if the starting offset exceeds 2GB minus 2 bytes and the file was not opened for large file access.

Related Information

Example

The following example opens a file and reads input:


#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>

main() {
  int ret, file_descriptor;
  char buf[]="Test text";

  file_descriptor = creat("test.output", S_IWUSR);
  write(file_descriptor, buf, sizof(buf)-1);
  close(file_descriptor);

  if ((file_descriptor = open("test.output", O_RDONLY)) < 0)
    perror("open() error");
  else {
    ret = read(file_descriptor, buf, sizeof(buf)-1));
    buf[ret] = 0x00;
    printf("block read: \n<%s>\n", buf);
    close(file_descriptor);
  }

  unlink("test.output");
}

Output:

block read:
<Test text>

Top | Integrated File System APIs | APIs by category

[Information Center Home Page | Feedback ]

[Legal | AS/400 Glossary]