# mgetstr

reads a character string from a file

## Calling Sequence

    str = mgetstr(n, [fd])

## Arguments

n

  non-negative integer: how many characters should be read.

fd

  an integer: file descriptor as returned by mopen: where characters should be read. The value `-1` stands for the last opened file and is the default.

str

  the character string to be read.

## Description

The `mgetstr` function attempts to read up to `n` characters from a file. If end of file is reached before `n` characters are read, `mgetstr` returns the properly read values only. As a consequence, when the read cursor is already at the end of the file when `mgetstr` is called, it returns an empty string no matter what value is provided for `n`.

## Examples

          fn = SCI + '/ACKNOWLEDGEMENTS'; // absolute path to some file
          details = fileinfo(fn);         // retrieve file details
          len = details(1);               // get file length
          fd = mopen(fn, 'rt');           // open file as text with read mode
          str1 = mgetstr(33, fd)          // read 33 characters from fd
          length(str1)                    // 33 characters read
          str2 = mgetstr(272, fd)         // read the next 272 characters from fd
          length(str2)                    // 272 characters read
          mseek(len - 5);                 // jump to the 5th character before end of file
          str3 = mgetstr(10, fd)          // try to read 10 characters: returns 5 characters only, no more available
          length(str3)                    // yes, there are 5 characters: you just can't see the linefeed :)
          str4 = mgetstr(10, fd)          // read 10 characters: returns empty string
          length(str4)                    // empty string
          mclose(fd);                     // close file descriptor

## See Also

- mclose
- meof
- mfprintf
- fprintfMat
- mfscanf
- fscanfMat
- mget
- mopen
- mprintf
- mput
- mputstr
- mseek
- mtell
- mdelete
- "Input/Output functions" section