Add SPDX license (but not copyright) headers to all files which follow a
certain pattern in their existing non-machine-readable header comment.
This commit was entirely generated using the command:
```
git ls-files glib/*.[ch] | xargs perl -0777 -pi -e 's/\n \*\n \* This library is free software; you can redistribute it and\/or\n \* modify it under the terms of the GNU Lesser General Public/\n \*\n \* SPDX-License-Identifier: LGPL-2.1-or-later\n \*\n \* This library is free software; you can redistribute it and\/or\n \* modify it under the terms of the GNU Lesser General Public/igs'
```
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Helps: #1415
We said the type must support being cleaned up and will be cleaned up in
an appropriate way, but in order to figure out how to do that, you had
to jump forward in the documentation to the other macros. Just say them.
This makes it easier to maintain the documentation and code at the same
time. The documentation comments haven’t been modified.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
As we discovered in GNOME/gtk#1280, GCC considers the pragmas to control
the deprecation warnings as statements. This means we cannot just use
the GLib wrappers as markers around the call site, but we must be aware
of their side effects.
Let's document this, to avoid falling into the trap.
It would be nice if docs.c eventually went away — it’s more maintainable
for documentation comments to be next to the definition of the symbols
they document.
Move a few from docs.c, based on what I’ve been modifying recently.
The documentation comments are unchanged apart from fixing an argument
name for G_ALIGNOF.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
It isn't always obvious how and where to use these. Where possible I've
chosen real examples from GLib, preferring simple examples that
developers considering using these macros have hopefully already seen.
Signed-off-by: Simon McVittie <smcv@collabora.com>
Move them next to their definitions, so they’re more likely to be kept
up to date.
This doesn’t modify any of the documentation comments at all.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
They were changed in 6a2cfde2 to reuse the G_MAXINT values but
parsing nexted macros is currently broken in g-i and results in wrong
values.
Add value annotations for g-i to override the values.
This also moves the annotations to the macro definitions to have
everything g-i uses in one place.
It has different semantics from _Alignof and our G_STRUCT_OFFSET
fallback. See the comments in the diff for details.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
https://gitlab.gnome.org/GNOME/glib/issues/1055
Expands to the GNU C fallthrough statement attribute if the compiler is gcc.
This allows declaring case statement to explicitly fall through in switch
statements. To enable this feature, use -Wimplicit-fallthrough during
compilation.
Thanks to some great investigation by Benjamin Moody, it’s clear that
our documentation and usage of G_GNUC_MALLOC has fallen behind GCC’s
interpretation of the malloc attribute, meaning that recent versions of
GCC could miscompile code which uses G_GNUC_MALLOC incorrectly.
Update the documentation of G_GNUC_MALLOC to match the current GCC
documentation (for GCC 8.2). Following commits will drop our use of
G_GNUC_MALLOC from inappropriate functions.
Specifically, the change in GCC’s interpretation of the malloc attribute
which could cause miscompilation is that returned storage areas are now
assumed to not contain valid pointers — so realloc() cannot have the
malloc attribute, and neither can a function which returns a newly
allocated structure with fields initialised to other pointers.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
https://gitlab.gnome.org/GNOME/glib/issues/1465
The current docs implied, by using the printf name, that the macros would
be compatible with printf(), but that's not always the case.
On Windows we use gnulib if the system printf isn't good enough.
This can happen on MinGW without __USE_MINGW_ANSI_STDIO set or with MSVC
with a varrying degree of incompatibility.
https://bugzilla.gnome.org/show_bug.cgi?id=795569
off64_t doesn’t exist in any standard (definitely not C99), and so
goffset is actually closer to off_t in 64-bit mode.
However, goffset is always defined as gint64, so make that clear.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
https://bugzilla.gnome.org/show_bug.cgi?id=792856
gtk-doc doesn’t support them any more since it was ported to Markdown,
so they end up appearing in the generated documentation, which isn’t
great.
Mostly, they were used to split up things invisibly, which we can do in
other ways.
Signed-off-by: Philip Withnall <withnall@endlessm.com>
Reviewed-by: nobody
This will fix a few broken links in the documentation, and shut up a
load of gtk-doc warnings (but certainly not all of them).
Signed-off-by: Philip Withnall <withnall@endlessm.com>
https://bugzilla.gnome.org/show_bug.cgi?id=790015
All glib/*.{c,h} files have been processed, as well as gtester-report.
12 of those files are not licensed under LGPL:
gbsearcharray.h
gconstructor.h
glibintl.h
gmirroringtable.h
gscripttable.h
gtranslit-data.h
gunibreak.h
gunichartables.h
gunicomp.h
gunidecomp.h
valgrind.h
win_iconv.c
Some of them are generated files, some are licensed under a BSD-style
license and win_iconv.c is in the public domain.
Sub-directories inside glib/:
deprecated/: processed in a previous commit
glib-mirroring-tab/: already LGPLv2.1+
gnulib/: not modified, the code is copied from gnulib
libcharset/: a copy
pcre/: a copy
tests/: processed in a previous commit
https://bugzilla.gnome.org/show_bug.cgi?id=776504
Clarify that the arguments parameter can be zero if the function being
annotated just accepts a string format argument, and no varargs for it
(for example, if it takes a va_list of arguments instead).
Add some links to the GCC documentation for the `format` attribute.
It's been a long time since we've been unconditionally saying "static
inline" in GLib headers without complaints so it's safe to assume that
all compilers that we care about support this.
One thing that is not yet totally supported is the unadorned use of the
word "inline". Depending on the flags (-std=c89, for example), even GCC
will complain about this. Detect missing C99 support and define
"inline" to "__inline" in that case. Some research shows "__inline"
appears to be the most widely-supported keyword here, but we may need to
tweak this if we get some reports of breakage.
Clean up all of the configure checks around this and define G_CAN_INLINE
unconditionally. Unfortunately, we must assume that some people are
still using G_IMPLEMENT_INLINES, we must continue to implement that
(including undefining G_CAN_INLINE and redefining G_INLINE_FUNC) if
requested.
It is not our intent to break existing users of the old-style
G_INLINE_FUNC approach and if that has happened, we may need to make
some further adjustments.
https://bugzilla.gnome.org/show_bug.cgi?id=757374
Add some helpers for builds-checked unsigned integer arithmetic to GLib.
These will be based on compiler intrinsics where they are available,
falling back to standard manual checks otherwise.
The fallback case needs to be implemented as a function (which we do
inline) because we cannot rely on statement expressions. We also
implement the intrinsics case as an inline in order to avoid people
accidentally writing non-portable code which depends on static
evaluation of the builtin.
For now there is only support for addition and multiplication for guint,
guint64 and gsize. It may make sense to add support for subtraction or
for the signed equivalents of those types in the future if we find a use
for that.
https://bugzilla.gnome.org/show_bug.cgi?id=503096
The g_autoptr() being associated with the type name works out really
well for things like GHashTable. However, it's a bit more awkward to
associate with "gchar". Also because one can't use "char".
Similarly, there are a lot of other "bare primitive array" types that
one might reasonably use.
This patch does not remove the autoptr for "gchar", even though I
think it's rather awkward and strange.
Also while we're here, add a test case for the cleanup bits.
https://bugzilla.gnome.org/show_bug.cgi?id=744747
Add g_auto() and g_autoptr() as helpers for declaring variables with
automatic cleanup.
Add some macros to help types define cleanup functions for themselves.
Going forward it will be an expectation that people use this macro when
creating a new type, even if they do not intend to use the auto-cleanup
functionality for themselves.
These new macros only work on GCC and clang, which is why we resisted
adding them for so long. There exist many people who are only
interested in writing programs for these compilers, however, and a
similar API in libgsystem has proven to be extremely popular, so let's
expose this functionality to an even wider audience.
We ignore deprecation warnings when emitting the free functions, which
seems suspicious. The reason that we do this is not because we want to
call deprecated functions, but just the opposite: sometimes the free
function will be an _unref() function that is only AVAILABLE_IN newer
versions, and these warnings are also implemented as deprecation
warnings.
https://bugzilla.gnome.org/show_bug.cgi?id=743640
Since all element markup is now gone from the doc comments,
we can turn off the gtk-doc sgml mode, which means that from
now on, docbook markup is no longer allowed in doc comments.
To make this possible, we have to replace all remaining
entities in doc comments by their replacement text, & -> &
and so on.
