[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
https://github.com/balazske closed https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions +are detected: + +* The ``FILE *`` pointer passed to the function is NULL (the single exception is + ``fflush`` where NULL is allowed). +* Use of stream after close. +* Opened stream is not closed. +* Read from a stream after end-of-file. (This is not a fatal error but reported + by the checker. Stream remains in EOF state and the read operation fails.) balazske wrote: I have the feeling that these words (NULL, EOF) are relatively commonly used (NULL is an abbrevation for null pointer, EOF = end-of-file). Probably `NULL` can be better as keyword (code format), but by EOF I did not mean the numeric constant, just "end of file". https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
=?utf-8?q?Balázs_Kéri?= Message-ID: In-Reply-To: @@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions +are detected: + +* The ``FILE *`` pointer passed to the function is NULL (the single exception is + ``fflush`` where NULL is allowed). +* Use of stream after close. +* Opened stream is not closed. +* Read from a stream after end-of-file. (This is not a fatal error but reported + by the checker. Stream remains in EOF state and the read operation fails.) steakhal wrote: I can see `NULL` and `EOF` (maybe others) spelled in the docs without double backticks. Do you think we should escape those to have verbatim code highlighting? https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
https://github.com/balazske updated
https://github.com/llvm/llvm-project/pull/83858
From bb81a944b78315471df8866bf21b317e8c50166c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20K=C3=A9ri?=
Date: Mon, 4 Mar 2024 09:48:41 +0100
Subject: [PATCH 1/2] [clang][analyzer] Improve documentation of StreamChecker
(NFC).
---
clang/docs/analyzer/checkers.rst | 66 +---
1 file changed, 52 insertions(+), 14 deletions(-)
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index fe211514914272..aa79792c64dc54 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of
stream APIs: ``fopen, fcl
alpha.unix.Stream (C)
"
-Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite,
fseek, ftell, rewind, fgetpos,``
-``fsetpos, clearerr, feof, ferror, fileno``.
+Check C stream handling functions:
+``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc,
fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell,
ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``.
+
+The checker maintains information about the C stream objects (``FILE *``) and
+can detect error conditions related to use of streams. The following conditions
+are detected:
+
+* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush``
+ NULL is allowed.)
+* Use of stream after close.
+* Opened stream is not closed.
+* Read from a stream after end-of-file. (This is not a fatal error but reported
+ by the checker. Stream remains in EOF state and the read operation fails.)
+* Use of stream when the file position is indeterminate after a previous failed
+ operation. Some functions are allowed in this state.
+* Invalid 3rd ("``whence``") argument to ``fseek``.
+
+The checker is not capable of maintaining a relation between integer file
+descriptors and ``FILE *`` pointers. Operations on standard streams like
+``stdin`` are not treated specially and are therefore often not recognized
+(because these streams are usually not opened explicitly by the program, and
+are global variables).
.. code-block:: c
- void test() {
+ void test1() {
FILE *p = fopen("foo", "r");
} // warn: opened file is never closed
- void test() {
+ void test2() {
FILE *p = fopen("foo", "r");
fseek(p, 1, SEEK_SET); // warn: stream pointer might be NULL
fclose(p);
}
- void test() {
+ void test3() {
FILE *p = fopen("foo", "r");
+ if (p) {
+ fseek(p, 1, 3); // warn: third arg should be SEEK_SET, SEEK_END, or
SEEK_CUR
+ fclose(p);
+ }
+ }
- if (p)
- fseek(p, 1, 3);
- // warn: third arg should be SEEK_SET, SEEK_END, or SEEK_CUR
+ void test4() {
+ FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
fclose(p);
+ fclose(p); // warn: stream already closed
}
- void test() {
+ void test5() {
FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
+
+ fgetc(p);
+ if (!ferror(p))
+ fgetc(p); // warn: possible read after end-of-file
+
fclose(p);
- fclose(p); // warn: already closed
}
- void test() {
- FILE *p = tmpfile();
- ftell(p); // warn: stream pointer might be NULL
+ void test6() {
+ FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
+
+ fgetc(p);
+ if (!feof(p))
+ fgetc(p); // warn: file position may be indeterminate after I/O error
+
fclose(p);
}
-
.. _alpha-unix-cstring-BufferOverlap:
alpha.unix.cstring.BufferOverlap (C)
From 5d723d165331b9a3e38a2ea1c9ff83b70745b6e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20K=C3=A9ri?=
Date: Tue, 5 Mar 2024 10:25:46 +0100
Subject: [PATCH 2/2] maked documentation more exact
---
clang/docs/analyzer/checkers.rst | 16
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index aa79792c64dc54..e6eb7c2ced620c 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3027,21 +3027,21 @@ The checker maintains information about the C stream
objects (``FILE *``) and
can detect error conditions related to use of streams. The following conditions
are detected:
-* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush``
- NULL is allowed.)
+* The ``FILE *`` pointer passed to the function is NULL (the single exception
is
+ ``fflush`` where NULL is allowed).
* Use of stream after close.
* Opened stream is not closed.
* Read from a stream after end-of-file. (This is not a fatal error but reported
by the checker. Stream remains in EOF state and the read operation fails.)
* Use of stream when the file position is indeterminate after a previous failed
- operation. Some functions are allowed in this state.
+ operation. Some functions (like ``ferror``, ``clearerr``, ``fseek``) are
+ allowed in this state.
*
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions +are detected: + +* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush`` + NULL is allowed.) +* Use of stream after close. balazske wrote: This is not meant to be a function name, just "close of a stream" (I do not know why it is displayed in blue color). https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions balazske wrote: I do not know but "can detect error conditions related to use of streams" is good in itself so I would leave it. https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions +are detected: + +* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush`` benshi001 wrote: The ``FILE *`` pointer passed to a function is NULL. (except ''fflush'' which allows that) https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions +are detected: + +* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush`` + NULL is allowed.) +* Use of stream after close. benshi001 wrote: after '' fclose '' ? https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
https://github.com/benshi001 approved this pull request. https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions benshi001 wrote: `... related to use of these streams.` English is not my first language, maybe my suggestion is not good. https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fcl alpha.unix.Stream (C) " -Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,`` -``fsetpos, clearerr, feof, ferror, fileno``. +Check C stream handling functions: +``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc, fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell, ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``. + +The checker maintains information about the C stream objects (``FILE *``) and +can detect error conditions related to use of streams. The following conditions +are detected: + +* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush`` + NULL is allowed.) +* Use of stream after close. +* Opened stream is not closed. +* Read from a stream after end-of-file. (This is not a fatal error but reported + by the checker. Stream remains in EOF state and the read operation fails.) +* Use of stream when the file position is indeterminate after a previous failed + operation. Some functions are allowed in this state. benshi001 wrote: Some functions (such as ...) are allowed in this state. https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
https://github.com/benshi001 edited https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of
stream APIs: ``fopen, fcl
alpha.unix.Stream (C)
"
-Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite,
fseek, ftell, rewind, fgetpos,``
-``fsetpos, clearerr, feof, ferror, fileno``.
+Check C stream handling functions:
+``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc,
fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell,
ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``.
+
+The checker maintains information about the C stream objects (``FILE *``) and
+can detect error conditions related to use of streams. The following conditions
+are detected:
+
+* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush``
+ NULL is allowed.)
+* Use of stream after close.
+* Opened stream is not closed.
+* Read from a stream after end-of-file. (This is not a fatal error but reported
+ by the checker. Stream remains in EOF state and the read operation fails.)
+* Use of stream when the file position is indeterminate after a previous failed
+ operation. Some functions are allowed in this state.
+* Invalid 3rd ("``whence``") argument to ``fseek``.
+
+The checker is not capable of maintaining a relation between integer file
NagyDonat wrote:
```suggestion
The checker does not track the correspondence between integer file
```
and re-apply line wrapping to the paragraph (if needed)
https://github.com/llvm/llvm-project/pull/83858
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
https://github.com/NagyDonat approved this pull request. Looks reasonable. https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
https://github.com/NagyDonat edited https://github.com/llvm/llvm-project/pull/83858 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
llvmbot wrote:
@llvm/pr-subscribers-clang
@llvm/pr-subscribers-clang-static-analyzer-1
Author: Balázs Kéri (balazske)
Changes
---
Full diff: https://github.com/llvm/llvm-project/pull/83858.diff
1 Files Affected:
- (modified) clang/docs/analyzer/checkers.rst (+52-14)
``diff
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index fe211514914272..aa79792c64dc54 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of
stream APIs: ``fopen, fcl
alpha.unix.Stream (C)
"
-Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite,
fseek, ftell, rewind, fgetpos,``
-``fsetpos, clearerr, feof, ferror, fileno``.
+Check C stream handling functions:
+``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc,
fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell,
ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``.
+
+The checker maintains information about the C stream objects (``FILE *``) and
+can detect error conditions related to use of streams. The following conditions
+are detected:
+
+* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush``
+ NULL is allowed.)
+* Use of stream after close.
+* Opened stream is not closed.
+* Read from a stream after end-of-file. (This is not a fatal error but reported
+ by the checker. Stream remains in EOF state and the read operation fails.)
+* Use of stream when the file position is indeterminate after a previous failed
+ operation. Some functions are allowed in this state.
+* Invalid 3rd ("``whence``") argument to ``fseek``.
+
+The checker is not capable of maintaining a relation between integer file
+descriptors and ``FILE *`` pointers. Operations on standard streams like
+``stdin`` are not treated specially and are therefore often not recognized
+(because these streams are usually not opened explicitly by the program, and
+are global variables).
.. code-block:: c
- void test() {
+ void test1() {
FILE *p = fopen("foo", "r");
} // warn: opened file is never closed
- void test() {
+ void test2() {
FILE *p = fopen("foo", "r");
fseek(p, 1, SEEK_SET); // warn: stream pointer might be NULL
fclose(p);
}
- void test() {
+ void test3() {
FILE *p = fopen("foo", "r");
+ if (p) {
+ fseek(p, 1, 3); // warn: third arg should be SEEK_SET, SEEK_END, or
SEEK_CUR
+ fclose(p);
+ }
+ }
- if (p)
- fseek(p, 1, 3);
- // warn: third arg should be SEEK_SET, SEEK_END, or SEEK_CUR
+ void test4() {
+ FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
fclose(p);
+ fclose(p); // warn: stream already closed
}
- void test() {
+ void test5() {
FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
+
+ fgetc(p);
+ if (!ferror(p))
+ fgetc(p); // warn: possible read after end-of-file
+
fclose(p);
- fclose(p); // warn: already closed
}
- void test() {
- FILE *p = tmpfile();
- ftell(p); // warn: stream pointer might be NULL
+ void test6() {
+ FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
+
+ fgetc(p);
+ if (!feof(p))
+ fgetc(p); // warn: file position may be indeterminate after I/O error
+
fclose(p);
}
-
.. _alpha-unix-cstring-BufferOverlap:
alpha.unix.cstring.BufferOverlap (C)
``
https://github.com/llvm/llvm-project/pull/83858
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [clang][analyzer] Improve documentation of StreamChecker (NFC). (PR #83858)
https://github.com/balazske created
https://github.com/llvm/llvm-project/pull/83858
None
From bb81a944b78315471df8866bf21b317e8c50166c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20K=C3=A9ri?=
Date: Mon, 4 Mar 2024 09:48:41 +0100
Subject: [PATCH] [clang][analyzer] Improve documentation of StreamChecker
(NFC).
---
clang/docs/analyzer/checkers.rst | 66 +---
1 file changed, 52 insertions(+), 14 deletions(-)
diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index fe211514914272..aa79792c64dc54 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3020,44 +3020,82 @@ Check for misuses of stream APIs. Check for misuses of
stream APIs: ``fopen, fcl
alpha.unix.Stream (C)
"
-Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite,
fseek, ftell, rewind, fgetpos,``
-``fsetpos, clearerr, feof, ferror, fileno``.
+Check C stream handling functions:
+``fopen, fdopen, freopen, tmpfile, fclose, fread, fwrite, fgetc, fgets, fputc,
fputs, fprintf, fscanf, ungetc, getdelim, getline, fseek, fseeko, ftell,
ftello, fflush, rewind, fgetpos, fsetpos, clearerr, feof, ferror, fileno``.
+
+The checker maintains information about the C stream objects (``FILE *``) and
+can detect error conditions related to use of streams. The following conditions
+are detected:
+
+* The ``FILE *`` pointer passed to the function is NULL. (At ``fflush``
+ NULL is allowed.)
+* Use of stream after close.
+* Opened stream is not closed.
+* Read from a stream after end-of-file. (This is not a fatal error but reported
+ by the checker. Stream remains in EOF state and the read operation fails.)
+* Use of stream when the file position is indeterminate after a previous failed
+ operation. Some functions are allowed in this state.
+* Invalid 3rd ("``whence``") argument to ``fseek``.
+
+The checker is not capable of maintaining a relation between integer file
+descriptors and ``FILE *`` pointers. Operations on standard streams like
+``stdin`` are not treated specially and are therefore often not recognized
+(because these streams are usually not opened explicitly by the program, and
+are global variables).
.. code-block:: c
- void test() {
+ void test1() {
FILE *p = fopen("foo", "r");
} // warn: opened file is never closed
- void test() {
+ void test2() {
FILE *p = fopen("foo", "r");
fseek(p, 1, SEEK_SET); // warn: stream pointer might be NULL
fclose(p);
}
- void test() {
+ void test3() {
FILE *p = fopen("foo", "r");
+ if (p) {
+ fseek(p, 1, 3); // warn: third arg should be SEEK_SET, SEEK_END, or
SEEK_CUR
+ fclose(p);
+ }
+ }
- if (p)
- fseek(p, 1, 3);
- // warn: third arg should be SEEK_SET, SEEK_END, or SEEK_CUR
+ void test4() {
+ FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
fclose(p);
+ fclose(p); // warn: stream already closed
}
- void test() {
+ void test5() {
FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
+
+ fgetc(p);
+ if (!ferror(p))
+ fgetc(p); // warn: possible read after end-of-file
+
fclose(p);
- fclose(p); // warn: already closed
}
- void test() {
- FILE *p = tmpfile();
- ftell(p); // warn: stream pointer might be NULL
+ void test6() {
+ FILE *p = fopen("foo", "r");
+ if (!p)
+ return;
+
+ fgetc(p);
+ if (!feof(p))
+ fgetc(p); // warn: file position may be indeterminate after I/O error
+
fclose(p);
}
-
.. _alpha-unix-cstring-BufferOverlap:
alpha.unix.cstring.BufferOverlap (C)
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
