diff options
Diffstat (limited to 'man/bib-add.1')
| -rw-r--r-- | man/bib-add.1 | 33 |
1 files changed, 30 insertions, 3 deletions
diff --git a/man/bib-add.1 b/man/bib-add.1 index 5c7a674..32582c5 100644 --- a/man/bib-add.1 +++ b/man/bib-add.1 @@ -21,14 +21,41 @@ If an incoming entry's key already exists in the database, the entry is rejected and the duplicate keys are reported on standard error, unless .B \-f is given. +Input with an empty key, or with the same key appearing twice, is +always rejected. +.SH SAFETY +The database is never modified in place. +The complete new version is built in a temporary file alongside the +original, verified by re-parsing it and checking that exactly the +expected entries are present, and only then written over the database +\(em with the previous contents first saved in +.IB db.bib .bak\fR. +If anything fails along the way, the original file is left untouched. +.PP +Concurrent invocations are serialized through a lock file, +.IB db.bib .lock\fR, +created atomically with the owner's pid inside. +A waiter retries for 30 seconds before giving up with an error; +a lock whose owning process has died is reaped automatically. .SH OPTIONS .TP .B \-f Replace existing entries that share a key with an incoming entry. -The database is rewritten canonically in the process. +The replaced entries are spliced out by their exact source spans, so +comments and the formatting of every other entry are preserved +byte-for-byte. .SH EXIT STATUS -0 on success, 1 if no entries were read or a duplicate key was -rejected, 2 on usage error. +0 on success, 1 if the input was rejected or the database could not +be safely rewritten, 2 on usage error. +.SH FILES +.TP +.IB db.bib .bak +The previous contents of the database, written before each +modification. +.TP +.IB db.bib .lock +Write lock held for the duration of an invocation; contains the +owner's pid. .SH ENVIRONMENT .TP .B BIBUTILS_LIB |