read()--Read from Descriptor


  Syntax
 #include <unistd.h>

 ssize_t read(int file_descriptor,
             void *buf, size_t nbyte);
  Service Program Name: QP0LLIB1

  Default Public Authority: *USE

  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 maximum number of bytes on a single read that can be supported for text data is 2,147,483,408 (2GB - 240) bytes. The data is converted from the code page of the file to the code page of the application, job, or system as follows:

There are some important considerations when the file is open for text conversion and the CCSIDs involved are not strictly single-byte:

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 and independent ASP QSYS.LIB file systems, most end-of-file characters are symbolic; that is, they are stored outside the member. When reading:

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.

When attempting to read from an empty pipe or FIFO:


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.

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

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



Error Messages

The following messages may be sent from this function:



Usage Notes

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

  2. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

    This function will fail with error code [ENOTSAFE] if the object on which this function is operation is a save file and multiple threads exist in the job.

    This function will fail with error code [EIO] if the file specified is a save file and the file does not contain complete save file data.

    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.


  3. QOPT File System Differences

    The file access time is not updated on a read() operation.

    When reading from files on volumes formatted in Universal Disk Format (UDF), byte locks on the range being read are ignored.


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


  5. QFileSvr.400 File System Differences

    When connecting to a system at release V5R4M5 and earlier, QFileSvr.400 does not support large files. Otherwise, the starting offset is limited by the file system being accessed on the server.


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

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

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

  9. Using this function successfully on the /dev/null or /dev/zero character special file results in a return value of zero. In addition, the access time for the file is updated.

Related Information


Example

The following example opens a file and reads input.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

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

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

  if ((file_descriptor = creat("test.output", S_IWUSR))!= 0)
     perror("creat() error");
  else {
    if (-1==(rc=write(file_descriptor, buf, sizof(buf)-1)))
       perror("write() error");
    if (close(file_descriptor)!= 0)
       perror("close() error");
  }

  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>\", buf);
    if (close(file_descriptor)!= 0)
       perror("close() error");
  }
  if (unlink("test.output")!= 0)
     perror("unlink() error");
}

Output:

block read:
<Test text>


API introduced: V3R1

[ Back to top | UNIX-Type APIs | APIs by category ]