... when referring to a function's parameter or a struct/union's
member.
The idea of using FOO comes from the GNU coding standards:
The comment on a function is much clearer if you use the argument
names to speak about the argument values. The variable name
itself should be lower case, but write it in upper case when you
are speaking about the value rather than the variable itself.
Thus, "the inode number NODE_NUM" rather than "an inode".
Upcasing names is problematic for a case-sensitive language like C,
because it can create ambiguity. Moreover, it's too much shouting for
my taste.
GTK-Doc's convention to prefix the identifier with @ makes references
to variables stand out nicely. The rest of the GTK-Doc conventions
make no sense for us, however.
Signed-off-by: Markus Armbruster <armbru@pond.sub.org>
ef_ensure_space() oopses on negative ID, but succeeds anyway. edit()
proceeds to ef_write(), which neglects to check for negative ID.
Since the ID isn't in the cache, it then passes a NULL old element to
callback prewrite(), which crashes.
Fix ef_ensure_space() to fail on negative ID. Commit 5173f8cd
(v4.3.0) made it oops, but neglected to make it fail.
Fix ef_write() to oops and fail on negative ID.
ef_write() still passes NULL old element to prewrite() when the ID
isn't in the cache. Doesn't actually happen, because we use
prewrite() callbacks only with fully cached tables. Fragile. Make
ef_open() fail when that assumption is violated.
empdump -i now complains about extra rows instead of silently growing
the file to a size the server will reject. Affects tables sector,
nation, realms, game.
Bonus fix: better error message on I/O error or insufficient memory.
New struct empfile member nent replaces ef_open() parameter nelt.
Cleaner, because the expected size is a property of the file, not of
how it's used. Also fixes empdump to check file sizes.
Complication: with EFF_CREATE, ef_open() creates an empty file, to be
extended to the correct size. Callers passed nelt argument -1 along
with EFF_CREATE, to make ef_open() accept the empty file. Can't do
the same for empfile member nent. Instead, make ef_open() not check
the (zero) size then.
Replaces commit 5750107b, v4.3.15.
New struct empfile member base replaces ef_open_view() parameter base.
Cleaner, because the base table is a property of the view, not of how
it's used.
Use it to clean up verify_fail()'s base table access, and for extra
sanity checks in ef_open() and ef_open_view().
ef_open() handles onresize() failing incorrectly. Instead of fixing
that, drop the failure mode. It's not really used: unit_onresize()
fails only when used incorrectly. It isn't. If it ever is, ignoring
the failure is safe.
Make ef_close() clear them always, even for views. Harmless, as
ef_open_view() always sets the same flags.
Drop redundant assignment to ep->flags in ef_open(). ef_close()
clears mutable flags, no need to clear them some more right before
calling it. Missed in commit 3eb3607f, v4.3.0.
The message claims the file is larger than it actually is. Broken
since commit 71908018 (v4.3.0) implemented static cache in ef_open().
Harmless, because no file-backed table has a statically allocated
cache.
Why upgrade? I'm not a lawyer, but here's my take on the differences
to version 2:
* Software patents: better protection against abuse of patents to
prevent users from exercising the rights under the GPL. I doubt
we'll get hit with a patent suit, but it's a good move just on
general principles.
* License compatibility: compatible with more free licenses, i.e. can
"steal" more free software for use in Empire. I don't expect to steal
much, but it's nice to have the option.
* Definition of "source code": modernization of some details for today's
networked world, to make it easier to distribute the software. Not
really relevant to us now, as we normally distribute full source code.
* Tivoization: this is about putting GPL-licensed software in hardware,
then make the hardware refuse to run modified software. "Neat" trick
to effectively deny its users their rights under the GPL. Abuse was
"pioneered" by TiVo (popular digital video recorders). GPLv3 forbids
it. Unlikely to become a problem for us.
* Internationalization: more careful wording, to harden the license
outside the US. The lawyers tell us it better be done that way.
* License violations: friendlier way to deal with license violations.
This has come out of past experience enforcing the GPL.
* Additional permissions: Probably not relevant to us.
Also include myself in the list of principal authors.
Oops when a stale copy is written back, i.e. the processor was yielded
since the copy was made. Such bugs are difficult to spot. Sequence
numbers catch them when they do actual harm (they also catch different
bugs). Generation numbers catch them even when they don't.
New ef_generation to count generations. Call new ef_make_stale() to
increment it whenever the processor may be yielded.
New struct emptypedstr member generation. To conserve space, make it
a bit-field of twelve bits, i.e. generations are only recorded modulo
2^12. Make sure all members of unit empobj_storage share it. It is
only used in copies; its value on disk and in the cache is
meaningless. Copies with generation other than ef_generation are
stale. Stale copies that are a multiple of 2^12 generations old can't
be detected, but that is sufficiently improbable.
Set generation to ef_generation by calling new ef_mark_fresh() when
making copies in ef_read() and ef_blank(). nav_ship() and
fltp_to_list() make copies without going through ef_read(), and
therefore need to call ef_mark_fresh() as well. Also call it in
obj_changed() to make check_sect_ok() & friends freshen their argument
when it is unchanged.
New must_be_fresh() oopses when its argument is stale. Call it in
ef_write() to catch write back of stale copies.
A sequence number mismatch occurs when an invalid copy (with a stale
sequence number) gets written. To continue after the error, we need
to use the current sequence number. But new_seqno() used the larger
one of the two, which is correct only as long as sequence numbers do
not overflow. Overflow is rather unlikely, though.
Put the Windows code into new open_locked() instead. It's ugly having
that in file.c, but the fakes are ugly too, and somewhat brittle.
Remove posix_open(), F_SETLK, F_RDLCK, F_WRLCK, struct flock, and
simplify fcntl().
Really belongs there, because it manipulates empfile[].
New ef_open_view() to replace ef_init_view(). Make ef_close() cope
with views, and remove ef_fina_view(). Make ef_extend() and
ef_truncate() oops on views.
Xundump had special hackery to maintain configuration tables'
sentinels: xubody() and getobj() added a sentinel element when
initializing or growing a table, which xubody() stripped off again
before returning. The latter was an unclean hack.
Replace this by building knowledge of sentinels into struct empfile:
new flag EFF_SENTINEL, set for the appropriate members of empfile[],
obeyed by ef_extend() and ef_truncate().
Change ef_close() to log ep->file instead of ep->name, to match
ef_open().
Fix ef_extend() to log ep->name instead of ep->file, which could be
null. Also fix ef_ensure_space()'s function comment. Both broken in
commit 2eb8672b.
ef_truncate()'s error logging lacked detail when ef_realloc_cache()
failed, fix.
This oopses on output dependency violations, e.g. two threads doing a
read-modify-write without synchronization, or the one thread nesting
several read-modify-writes. Such bugs are difficult to spot, and tend
to be abusable. I figure we have quite a few of them.
New struct emptypedstr member seqno. Make sure all members of unit
empobj_storage share it. Initialize it in files: main() and
file_sct_init(). Set it in ef_blank() and new ef_set_uid() by calling
new get_seqno(). Use ef_set_uid() when copying objects: swaps(),
doland(), doship(), doplane(), dounit(), delete_old_news(). Step it
in ef_write() by calling new new_seqno().
Factor do_read() out of fillcache() to make it available for
get_seqno().
Commit f33b96b1 (v4.3.12) made files again set timestamps. That was
intentionally suppressed in commit 990eb46b (v4.3.10), because it
facilitates attacks against the PRNG. Commit 8f98e53a (v4.3.0) had
added it as a feature.
Fix by making files's main() pass new flag EFF_NOTIME to ef_open().
Implement the flag in do_write().
do_write() sets the timestamp from a parameter. All callers pass
time(), and don't use that value themselves. Call time() in do_write
and remove the parameter.
Commit f33b96b1 made ef_flush(), ef_write() and ef_extend() update
timestamps automatically. Change ef_write() and ef_extend() to do
that even when table is privately mapped, by making do_write() cope
with privately mapped tables. Current users don't care, but it's a
saner interface.
Certain tables have a fixed size depending on configuration: EF_SECTOR
has WORLD_SZ() elements, EF_NATION, EF_MAP and EF_BMAP have MAXNOC
elements, and EF_REALM has MAXNOC * MAXNOR elements. Bad things
happen if the files backing them are shorter.
Pass expected size to ef_open(), and make it fail when the actual size
differs.
