fgets

Read line from file, keep newline character

Syntax

• tline = fgets(fid)
  tline = fgets(fid,nchar)
  

Description

tline = fgets(fid) returns the next line of the file associated with file identifier fid. If fgets encounters the end-of-file indicator, it returns -1. (See fopen for a complete description of fid.) fgets is intended for use with text files only.

The returned string tline includes the line terminators associated with the text line. To obtain the string without the line terminators, use fgetl.

tline = fgets(fid,nchar) returns at most nchar characters of the next line. No additional characters are read after the line terminators or an end-of-file.

fgets (serial)

Read one line of text from the device and include the terminator

Syntax

• tline = fgets(obj)
  [tline,count] = fgets(obj)
  [tline,count,msg] = fgets(obj)
  

Arguments

obj	A serial port object.
tline	Text read from the instrument, including the terminator.
count	The number of bytes read, including the terminator.
msg	A message indicating if the read operation was unsuccessful.

Description

tline = fgets(obj) reads one line of text from the device connected to obj, and returns the data to tline. The returned data includes the terminator with the text line. To exclude the terminator, use fgetl.

[tline,count] = fgets(obj) returns the number of values read to count.

[tline,count,msg] = fgets(obj) returns a warning message to msg if the read operation was unsuccessful.

Remarks

Before you can read text from the device, it must be connected to obj with the fopen function. A connected serial port object has a Status property value of open. An error is returned if you attempt to perform a read operation while obj is not connected to the device.

If msg is not included as an output argument and the read operation was not successful, then a warning message is returned to the command line.

The ValuesReceived property value is increased by the number of values read - including the terminator - each time fgets is issued.

If you use the help command to display help for fgets, then you need to supply the pathname shown below.

• help serial/fgets
  

Rules for Completing a Read Operation with fgets

A read operation with fgets blocks access to the MATLAB command line until:

• The terminator specified by the Terminator property is reached.
• The time specified by the Timeout property passes.
• The input buffer is filled.

Example

Create the serial port object s, connect s to a Tektronix TDS 210 oscilloscope, and write the RS232? command with the fprintf function. RS232? instructs the scope to return serial port communications settings.

• s = serial('COM1');
  fopen(s)
  fprintf(s,'RS232?')
  

Because the default value for the ReadAsyncMode property is continuous, data is automatically returned to the input buffer.

• s.BytesAvailable
  ans =
      17
  

Use fgets to read the data returned from the previous write operation, and include the terminator.

• settings = fgets(s)
  settings =
  9600;0;0;NONE;LF
  length(settings)
  ans =
      17
  

Disconnect s from the scope, and remove s from memory and the workspace.

• fclose(s)
  delete(s)
  clear s