pread()--Read from Descriptor with Offset

 #include <unistd.h>

 ssize_t pread(int file_descriptor,
             void *buf, size_t nbyte, off_t offset);  

From the file indicated by file_descriptor, the pread() function reads nbyte bytes of input into the memory area indicated by buf. The offset value defines the starting position in the file and the file pointer position is not changed.

See read()--Read from Descriptor for more information relating to reading from a descriptor.

In the QSYS.LIB and independent ASP QSYS.LIB file systems, the offset will be ignored for a member while in text mode.

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.

offset

(Input) The offset to the desired starting position in the file.

Authorities

No authorization is required.

Return Value

Error Conditions

If pread() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could also 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 specified 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 pread() 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 file systems that do not support large files, pread() 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, pread() will return [EOVERFLOW] if the starting offset exceeds 2GB minus 2 bytes and the file was not opened for large file access.
   
   
7. 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.
   
   
8. If file_descriptor refers to a descriptor obtained using the open() API with O_TEXTDATA and O_CCSID specified, the file CCSID and open CCSID are not the same, and the converted data could expand or contract, then the offset value must be 0.
   
   
9. If file_descriptor refers to a character special file, the offset value is ignored.

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
• pread64()--Read from Descriptor with Offset (large file enabled)
• pwrite()--Write to Descriptor with Offset
• pwrite64()--Write to Descriptor with Offset (large file enabled)
• read()--Read from Descriptor
• 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;
  off_t off=5;
  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 = pread(file_descriptor, buf, ((sizeof(buf)-1)-off), off);
    buf[ret] = 0x00;
    printf("block pread: \n<%s>\n", buf);
    if (close(file_descriptor)!= 0)
       perror("close() error");
  }
  if (unlink("test.output")!= 0)
     perror("unlink() error");
}

Output:

block pread:
<text>