Page History

An in-band error indicator is a value returned by a method that indicates either a legitimate return value or an illegitimate value that indicates an error. Some common examples of in-band error indicators include

• A valid object or a null reference.
• An integer indicating a positive value, or −1 to indicate that an error occurred.
• An array of valid objects or a null reference indicating the absence of valid objects. (This topic is further addressed in MET55-J. Return an empty array or collection instead of a null value for methods that return an array or collection)

In-band error indicators require checking for the error; however, this checking is often overlooked. Failure to check for such error conditions not only violates EXP00-J. Do not ignore values returned by methods but also has the unfortunate effect of propagating invalid values that may subsequently be treated as valid in later computations.

Avoid the use of in-band error indicators. These They are much less common in Java's core library than in some other programming languages; nevertheless, but they are used in the read(byte[] b, int off, int len) and read(char[] cbuf, int off, int len) family families of methods in java.io.

In Java, the best way to indicate an exceptional situation is by throwing an exception , rather than by returning an error code. Exceptions cannot are propagated across scopes and cannot be ignored in the same way that as easily as error codes can, and exceptions are propagated across scopes. When using exceptions, the error-detection and error-handling code is kept separate from the main flow of control. Also, exceptions can be used in situations where error codes cannot be returned (in constructors, for example).

Noncompliant Code Example

This noncompliant code example attempts to read into an array of characters and the to add an extra character into the buffer immediately after the characters that are read.

static final int MAX = 21;
static final int MAX_READ = MAX - 1;
static final char TERMINATOR = '\\';
int read;
char [] chBuff = new char [MAX];
BufferedReader buffRdr;

// setSet up buffRdr

read = buffRdr.read(chBuff, 0, MAX_READ);
chBuff[read] = TERMINATOR;

However, if the input buffer is initially at end-of-file then , the read method will return -1 −1, and the attempt to place the termintor terminator character will throw an ArrayIndexOutOfBoundsException.

Compliant Solution (

...

Wrapping)

This compliant solution defines a SafeBufferedReader class and introduces a readSafe() method that wraps the original read() method and throws an exception if end-of-file is detected.:

classpublic SafeBufferedReaderstatic extendsint readSafe(BufferedReader {
   SafeBufferedReader(Reader in) {
      super(in);
   }

   public int readSafe(char[] cbuf, int off, int len) throws EOFException {
      int read = read(cbuf, off, len);
      if (read == -1) {
         throw new EOFException();
      } else {buffer, char[] cbuf, 
         return read;
      }
   }
}

// ...

SafeBufferedReader safeBuffRdr;

try {
   read = safeBuffRdr.readSafe(chBuff, 0, MAX_READ);
   chBuff[read] = TERMINATOR;
} catch (EOFException eof) {
   chBuff[0] = TERMINATOR;
}

Compliant Solution (Wrapping)

This compliant solution defines a readSafe method that wraps the original read method and throws an exception if end-of-file is detected.

public static int readSafe(BufferedReader buffer, char[] cbuf, int off, int len) throws IOException {
  int read = buffer.read(cbuf, off, len);
  if (read == -1) {
     throw new EOFException();
  } else {
     return read;
  }
}

// ...

BufferedReader buffRdr;

// setSet up buffRdr

try {
   read = readSafe(buffRdr, chBuff, 0, MAX_READ);
   chBuff[read] = TERMINATOR;
} catch (EOFException eof) {
   chBuff[0] = TERMINATOR;
}

...

Applicability

Using in-band error indicators may result in programmers either failing to check status codes or using incorrect return values, resulting in undefined behavior.

Automated Detection

leading to unexpected behavior.

Given the comparatively rare occurrence of in-band error indicators in Java, it may be possible to compile a list of all standard library methods that use them and to automatically detect their use. However, detecting the safe use of in-band error indicators is not feasible .

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this guideline on the CERT website.

Other Languages

This guideline appears in the C Secure Coding Standard as ERR02-C. Avoid in-band error indicators and the C++ Secure Coding Standard as ERR07-CPP. Use exception handling rather than error codes.

Bibliography

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="8b002ecd-e9e2-441a-82d8-9be4488d454f"><ac:plain-text-body><![CDATA[

...

[[API 2006

...

AA. References#API 06]]

...

[Class Reader

...

http://download.oracle.com/javase/6/docs/api/java/io/Reader.html]

...

]]></ac:plain-text-body></ac:structured-macro>

in the general case.

Returning an object that might be null on failure or a valid object on success is a common example of in-band error indicator. Although better method designs are often available, returning an object that may be null can be acceptable under some circumstances. See MET54-J. Always provide feedback about the resulting value of a method for an example.

Bibliography

...

Image Added Image Added Image Added

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="d6f8689d-f8e3-46ac-859c-8d7221160de3"><ac:plain-text-body><![CDATA[

...

[[JLS 2011

...

AA. References#JLS 11]]

...

Chapter 11. Exceptions

...