read()--Read from Descriptor

 #include <unistd.h>

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

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:

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

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

• The read() will return the exact number of bytes requested. For some CCSIDs, this may mean that partial characters are returned at the end of the user buffer. In this case, the remainder of the character has been read from the file and internally buffered. The next consecutive read() will begin with the remainder of the partial character. However, if an lseek() is performed, the buffered data will be discarded. See lseek()--Set File Read/Write Offset for more information.
  
• Because of the above consideration and because of the possible expansion or contraction of converted data, applications using the O_CCSID flag should avoid assumptions about data size and the current file offset. For example, a file might have a physical size of 100 bytes, but after an application has read 100 bytes from the file, the current file offset may be 50. In order to read the whole file, the application might have to read 200 bytes or more, depending on the CCSIDs involved.

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:

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

When attempting to read from an empty pipe or FIFO:

• If no job has the pipe or FIFO open for writing, read() return 0 to indicate end-of-file.
  
• If some job has the pipe or FIFO open for writing and O_NONBLOCK was specified, read() will fail and errno will be set to [EAGAIN].
  
• If some job has the pipe or FIFO open for writing and O_NONBLOCK was not specified, read() will block the calling thread until some data is written or until the pipe or FIFO is closed by all jobs that had the pipe or FIFO open for writing.

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

   The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will be received.

   
   
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

• The <limits.h> file (see Header Files for UNIX-Type Functions)
• 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
• fclear()--Write (Binary Zeros) to Descriptor
• fclear64()--Write (Binary Zeros) to Descriptor (Large File Enabled)
• fcntl()--Perform File Control Command
• ioctl()--Perform I/O Control Request
• lseek()--Set File Read/Write Offset
• open()--Open File
• pread()--Read from Descriptor with Offset
• pread64()--Read from Descriptor with Offset (large file enabled)
• pwrite()--Write to Descriptor with Offset
• pwrite64()--Write to Descriptor with Offset (large file enabled)
• readv()--Read from Descriptor Using Multiple Buffers
• recv()--Receive Data
• recvfrom()--Receive Data
• recvmsg()--Receive Data or Descriptors or Both
• write()--Write to Descriptor
• writev()--Write to Descriptor Using Multiple Buffers

Example

See Code disclaimer information for information pertaining to code examples.

The following example opens a file and reads input:

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