---

C Library Functions  - get_next_char (3)

---

NAME

get_next_char(3f) - [M_io:READ] read from a file one character at a time (LICENSE:PD)

CONTENTS

Syntax
Description
Options
Examples
Author
License

SYNTAX

subroutine get_next_char(fd,c,ios)

    integer,intent(in)    :: fd
    character,intent(out) :: c
    integer,intent(out)   :: ios

DESCRIPTION

This reads a file opened with stream access one character at a time, much like ""read(fd,iostat=ios) c" but with buffering, which I have found to be up to sixty times faster than such a plain read, although this varies depending on how or if the programming environment implements I/O buffering itself.

    IT USES SAVED VARIABLES AND CAN ONLY BE USED ON ONE FILE AT A TIME

IN THE CURRENT FORM. A user type including the saved values and the LUN could easily resolve this.

OPTIONS

FD	A Fortran unit number of a file opened for stream access
C	The next returned character if IOS=0
IOS	The error status returned by the last read. It is zero (0) if no error occurred

EXAMPLES

Sample program:

   program demo_get_next_char
   use,intrinsic :: iso_fortran_env, only : iostat_end
   use M_io, only : get_next_char
   implicit none
   character(len=4096) :: filename ! filename to read
   character(len=256)  :: message  ! returned error messages
   integer             :: fd       ! file descriptor for input file
   integer             :: ios,ios1 ! hold I/O error flag
   character           :: c1       ! current character read
      filename=’test.in’
      open(unit=fd,file=trim(filename),access=’stream’,status=’old’,&
      & iostat=ios,action=’read’,form=’unformatted’,iomsg=message)
      if(ios /= 0)then
         write(*,*)&
         ’*demo_get_next_char* ERROR: could not open ’//&
         trim(filename)
         write(*,*)&
         ’*demo_get_next_char* ERROR: ’//trim(message)
         stop 5
      endif
      ! loop through read of file one character at a time
      ONE_CHAR_AT_A_TIME: do
         ! get next character from buffered read from file
         call get_next_char(fd,c1,ios1)
         if(ios1 == iostat_end)then
            ! reached end of file so stop
            stop
         elseif(ios1 /= 0 )then
            ! error on file read
            write(*,*)&
         ’*demo_get_next_char* ERROR: before end of ’//&
         trim(filename)
            stop 1
         endif
         ! do something with the characters
         write(*,’(a)’,advance=’no’)c1
      enddo ONE_CHAR_AT_A_TIME
   end program demo_get_next_char

AUTHOR

John S. Urban

LICENSE

Public Domain

---

Nemo Release 3.1

get_next_char (3)

February 23, 2025

Generated by manServer 1.08 from 68d782a0-8fff-40bd-806e-c99524cb07af using man macros.