Syntax

  #include <unistd.h> 
    
  LONG read  (  
     int    handle,   
     char  *buffer,   
     LONG   len);
  

Parameters

handle

(IN) Specifies a file handle.

buffer

(OUT) Points to a buffer to receive the data.

len

(IN) Specifies the number of bytes to read.

Return Values

read returns the number of bytes of data transmitted from the file to the buffer. Normally, this is the number given by the len parameter. When the end-of- file is encountered before the read completes, the return value is less than the number of bytes requested.

A value of -1 is returned when an input/output error is detected. If an error occurs, errno can be set to:

If read does not complete successfully, NetWareErrno is set.

Remarks

This function also works on the DOS partition.

The read function returns the number of bytes of data transmitted from the file to the buffer.

The handle value is returned by the open, sopen, creat, or fileno function. The access mode must have included either O_RDONLY or O_RDWR when the open or sopen function was invoked. The data is read starting at the current file position for the file in question. This file position can be determined with the tell function and can be set with the lseek function.

A read from a Stream file can operate in three different modes: byte-stream mode, message-nondiscard mode, and message-discard mode. The default is byte-stream mode. This can be changed using the I_SRDOPT ioctl request, and can be tested with the I_GRDOPT ioctl. In byte-stream mode, the read function retrieves data from the Stream until it has received nbyte bytes, or until there is no more data to be retrieved. Byte-stream mode ignores message boundaries.

In Stream message-nondiscard mode, the read function retrieves data until it has read nbytes bytes or until it reaches a message boundary. If the read function does not retrieve all the data in the message, the remaining data are placed on the Stream, and can be retrieved by the next read or getmsg call. Message-discard mode also retrieves data until it has retrieved nbyte bytes or it reaches a message boundary. However, unread data remaining in a message after the read function returns are discarded and are not available for a subsequent read or getmsg.

When reading from a Stream file, handling of zero-byte messages is determined by the current read mode setting. In byte-stream mode, the read function accepts data until it has read nbyte bytes, or until there is no more data to read or until a zero-byte message block is encountered. The read function returns the number of bytes read and places the zero-byte message back on the Stream to be retrieved by the next read or getmsg. In the two other modes, a zero-message returns a value of 0 and the message is removed from the Stream. When a zero-byte message is read as the first message on a Stream, a value of 0 is returned regardless of the read mode.

A read from a Stream file can only process data messages. It cannot process any type of protocol message and fails if a protocol message is encountered at the stream head.

A read from a Stream file also fails if an error message is received at the stream head. In this case, errno is set to the value returned in the error message. If a hang up occurs on the Stream being read, the read function continues to operate normally until the stream head read queue is empty. Thereafter, it returns 0.

See Also

close, creat, dup, dup2, eof, filelength, fileno, fstat, isatty, lseek, open, sopen, tell, write

Example

  #include <errno.h>  
  #include <fcntl.h>  
  #include <unistd.h>  
  #include <stddef.h>  
  #include <stdio.h>  
  #include <string.h>  
  #include <dirent.h>  
  #include <nwconio.h>  
   
  #define BUFFER_SIZE 512  
   
  main()  
  {  
     int     handle, rc, i, ch = 0;  
     char    buffer[BUFFER_SIZE];  
     handle = open ("test.dat", O_RDONLY, 0 );  
     if (handle < 0)  
     {  
        printf ("\r%s\r\n\n",strerror(errno));  
        exit (0);  
     }  
     while (1)  
     {  
        if ((rc = read (handle, buffer, BUFFER_SIZE)) <= 0)  
        {  
           lseek (handle,0,SEEK_SET);  
           rc = 0;  
        }  
        for (i = 0; i < rc; i++)  
        {  
           putchar (buffer[i] );  
           if (kbhit ())  
           {  
           if ((ch = getch()) == 0x03)  
           {  
              printf ("^C" );  
              close (handle );  
              exit (0);  
           }  
           else if(ch == ’l’)  
           {  
              printf ("\r\n\n***** lock %s\r\n\n",  
              lock (handle,1,10) ? "failed" : "succeeded");  
              getch ();  
           }  
           else if(ch == ’u’)  
           {  
              printf ("\r\n\n***** unlock %s\r\n\n",  
              unlock(handle,1,10) ? "failed" : "succeeded");  
              getch ();  
           }  
           else getch (); /* Pause*/  
           }  
        }  
     } 
  }