Linux-Sparse Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] manpage: annotations
@ 2020-07-03  0:04 Luc Van Oostenryck
  0 siblings, 0 replies; only message in thread
From: Luc Van Oostenryck @ 2020-07-03  0:04 UTC (permalink / raw)
  To: linux-sparse; +Cc: Luc Van Oostenryck

---
 sparse.1 | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/sparse.1 b/sparse.1
index d916ad9ee54e..068764799e00 100644
--- a/sparse.1
+++ b/sparse.1
@@ -18,6 +18,65 @@ option \fB\-Wsomething\fR.  Sparse issues some warnings by default; to turn
 off those warnings, pass the negation of the associated warning option,
 \fB\-Wno\-something\fR.
 .
+.SH ANNOTATIONS
+Sparse extends C's type system with a number of extra type qualifiers
+adding restrictions on what you can do on objects annotated with them.
+These qualifiers are specified with GCC's \fB__attribute__\fR syntax:
+.IP - 2
+bitwise
+.RS 2
+This attribute is to be used to define new, unique integer types that
+cannot be mixed with other types.
+In particular, you can't mix a "bitwise" integer with a normal integer
+expression, and in fact you can't even mix it with another bitwise
+expression of a different type.
+The integer 0 is special, though, and can be mixed with any bitwise type
+since it's safe for all bitwise operations.
+
+Since this qualifier defines new types, it only makes sense to use
+it in typedefs, which effectively makes each of these typedefs
+a single "bitwise class", incompatible with any other types.
+.RE
+.IP - 2
+force
+.RS 2
+This attribute is to be used in casts to suppress warnings that
+would be otherwise caused by this cast because of the presence of
+one of these qualifiers.
+.RE
+.IP - 2
+noderef
+.RS 2
+This attribute is to be used on a r-value to specify it cannot be
+dereferenced. A pointer so annotated is in all other aspects exactly
+like a pointer in all other respects, but trying to actually access
+anything through it will cause a warning.
+.RE
+.IP - 2
+address_space(\fIname\fR)
+.RS 2
+.RE
+.IP - 2
+context(\fIcontext\fR, \fIin\fR, \fIout\fR)
+.RS 2
+.RE
+.IP - 2
+nocast
+.RS 2
+This attribute is similar to \fBbitwise\fR but in a much weaker form.
+It is also 
+__nocast warns about explicit or implicit casting to different types
+however, the __nocast attribute disables many of the implicit type conversions
+
+.RE
+.IP - 2
+safe
+.RS 2
+This attribute specifies that the object, which should be a pointer,
+is defined to never be NULL or nontrapping.
+It causes a warning if the object is tested in a conditional.
+.RE
+
 .SH WARNING OPTIONS
 .TP
 .B \-fmax-warnings=COUNT
-- 
2.27.0

^ permalink raw reply	[flat|nested] only message in thread

only message in thread, back to index

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-03  0:04 [PATCH] manpage: annotations Luc Van Oostenryck

Linux-Sparse Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-sparse/0 linux-sparse/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-sparse linux-sparse/ https://lore.kernel.org/linux-sparse \
		linux-sparse@vger.kernel.org
	public-inbox-index linux-sparse

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-sparse


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git