ADMIN(1POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 ADMIN(1POSIX) 🌸

okay bestie, gather round — this is the POSIX Programmer's Manual page for admin, and it's giving absolute icon energy. 🎀

✨ PROLOG ✨

Real talk first: this manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — so if you're on Linux, bestie, go consult the corresponding Linux manual page for the deets on Linux behavior. Or… the interface may literally not be implemented on Linux at all. 💀 So vibe check your platform first, no cap.

🌈 NAME 🌈

admin — create and administer SCCS files (DEVELOPMENT)

it's giving "source code control but make it vintage" 🦋

💅 SYNOPSIS 💅

admin -i[name] [-n] [-a login] [-d flag] [-e login] [-f flag]
    [-m mrlist] [-r rel] [-t[name] [-y[comment]] newfile

admin -n [-a login] [-d flag] [-e login] [-f flag] [-m mrlist]
    [-t[name]] [-y[comment]] newfile...

admin [-a login] [-d flag] [-m mrlist] [-r rel] [-t[name]] file...

admin -h file...

admin -z file...

five whole forms, she contains multitudes 👑 ✨

🎀 DESCRIPTION 🎀

So the admin utility either creates brand-new SCCS files or changes the parameters of ones that already exist. That's the whole job, and she does it flawlessly. 💖

Here's the tea:

  • If a named file does not exist, it shall be created, and its parameters shall be initialized according to the options you specified. Any parameter you didn't initialize with an option gets assigned a default value. 🍓
  • If a named file does exist, then the parameters corresponding to the options you specified shall be changed, and every other parameter shall be left as is. Respectful. Iconic. Doesn't touch what she wasn't asked to touch. 🙈

now for the filename lore, bestie, this part matters:

All SCCS filenames supplied by the application shall be of the form s.filename. 🦋

New SCCS files shall be given read-only permission mode. Write permission in the parent directory is required to create a file. Yes, the parent directory — not the file itself. Don't get it twisted. 💅

All writing done by admin shall be to a temporary x-file, named x.filename (see get), created with read-only mode if admin is creating a new SCCS file, or created with the same mode as that of the SCCS file if the file already exists. 🌸

After successful execution of admin:

  1. The SCCS file shall be removed (if it exists).
  2. The x-file shall be renamed with the name of the SCCS file.
Why tho? Because this ensures that changes are made to the SCCS file only if no errors occur. ✨ Atomic-ish glow-up. We love a safety queen. 🫶

one more thing and then we move on:

The admin utility shall also use a transient lock file (named z.filename), which is used to prevent simultaneous updates to the SCCS file — see get. 🔒

no two admins editing at once, we're not doing chaos today 😭💜

...and that's just part one, bestie, keep scrolling, there's SO much more coming 🎀✨

✨ OPTIONS ✨

Okay bestie, so admin plays by the rules — specifically the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines — with one lil' exception: the -i, -t, and -y options have optional option-arguments. And heads up, those optional option-arguments shall not be handed over as separate arguments. Like, they gotta be glued on. Periodt.

Here's the full menu of what's supported:

  • -n — Make a brand new SCCS file. When you use -n without -i, the SCCS file gets created with all its control information but zero file data. Empty. A lil' baby file with just vibes and metadata.
  • -i[name] — Tell it which file the text for your new SCCS file should come from. That text becomes the first delta of the file (peep the -r option for how the delta numbering scheme works, iykyk). If you use -i but skip the name option-argument, the text gets read from standard input instead. And if you don't use -i at all? The SCCS file gets created with control information but no file data. Also super important: -i implies -n. They're a package deal.
  • -r SID — Set the SID of the initial delta you're inserting. This SID has to be a trunk SID — meaning the branch and sequence numbers shall be zero or just missing entirely. The level number is optional and defaults to 1. 🎀
  • -t[name] — Point it at a file to pull descriptive text for the SCCS file from. Now, if we're dealing with existing SCCS files (so, neither -i nor -n specified), here's the tea:
    • A -t option without a name option-argument shall cause the removal of descriptive text (if any) currently chillin' in the SCCS file.
    • A -t option with a name option-argument shall cause the text (if any) in the named file to replace the descriptive text (if any) currently in the SCCS file.
  • -f flag — Specify a flag, and possibly a value for that flag, to be placed in the SCCS file. You can stack several -f options on a single admin command line, no cap. Implementations shall recognize these flags and their associated values:
    • b — Allow use of the -b option on a get command to create branch deltas. 🌿
    • cceil — Specify the highest release (that is, the ceiling), a number less than or equal to 9999, which may be retrieved by a get command for editing. Default for an unspecified c flag shall be 9999.
    • ffloor — Specify the lowest release (that is, the floor), a number greater than 0 but less than 9999, which may be retrieved by a get command for editing. Default for an unspecified f flag shall be 1.
    • dSID — Specify the default delta number (SID) to be used by a get command.
    • istr — Treat the ``No ID keywords'' message issued by get or delta as a fatal error. Without this flag, that message is only a warning. The message gets issued if no SCCS identification keywords (see get) are found in the text retrieved or stored in the SCCS file. If a value is supplied, the application shall ensure that the keywords exactly match the given string — however, the string shall contain a keyword, and no embedded <newline> characters.
    • j — Allow concurrent get commands for editing on the same SID of an SCCS file. This lets multiple concurrent updates hit the same version of the SCCS file. 🫶
    • llist — Specify a list of releases to which deltas can no longer be made (so get -e against one of these locked releases fails). Conforming applications shall use this syntax to specify a list. Implementations may accept additional forms as an extension:
<list> ::= a | <range-list>
<range-list> ::= <range> | <range-list>, <range>
<range> ::= <SID>

The character a in the list shall be equivalent to specifying all releases for the named SCCS file. The non-terminal <SID> in range shall be the delta number of an existing delta associated with the SCCS file.

  • n — Cause delta to create a null delta in each of those releases (if any) being skipped when a delta is made in a new release (for example, in making delta 5.1 after delta 2.7, releases 3 and 4 are skipped). These null deltas act as anchor points so branch deltas may later be created from them. Without this flag, skipped releases shall be nonexistent in the SCCS file, which prevents branch deltas from being created from them in the future. During the initial creation of an SCCS file, the n flag may be ignored — that is, if the -r option is used to set the release number of the initial SID to a value greater than 1, null deltas need not be created for the ``skipped'' releases.
  • qtext — Substitute user-definable text for all occurrences of the %Q% keyword in the SCCS file text retrieved by get. ✨
  • mmod — Specify the module name of the SCCS file, substituted for all occurrences of the %M% keyword in the SCCS file text retrieved by get. If the m flag is not specified, the value assigned shall be the name of the SCCS file with the leading . removed.
  • ttype — Specify the type of module in the SCCS file, substituted for all occurrences of the %Y% keyword in the SCCS file text retrieved by get.
  • vpgm — Cause delta to prompt for modification request (MR) numbers as the reason for creating a delta. The optional value specifies the name of an MR number validation program. (If this flag is set when creating an SCCS file, the application shall ensure that the m option is also used even if its value is null.)
  • -d flag — Remove (delete) the specified flag from an SCCS file. Several -d options may be supplied on a single admin command. See the -f option for allowable flag names. (The llist flag gives a list of releases to be unlocked. See the -f option for more on the l flag and the syntax of a list.)
  • -a login — Specify a login name, or numerical group ID, to be added to the list of users who may make deltas (changes) to the SCCS file. A group ID shall be equivalent to specifying all login names common to that group ID. Several -a options may be used on a single admin command line. As many logins, or numerical group IDs, as desired may be on the list simultaneously. If the list of users is empty, then anyone may add deltas. If login or group ID is preceded by a '!', the users so specified shall be denied permission to make deltas.
  • -e login — Specify a login name, or numerical group ID, to be erased from the list of users allowed to make deltas (changes) to the SCCS file. Specifying a group ID is equivalent to specifying all login names common to that group ID. Several -e options may be used on a single admin command line.
  • -y[comment] — Insert the comment text into the SCCS file as a comment for the initial delta, in a manner identical to that of delta. In the POSIX locale, omitting the -y option shall result in a default comment line being inserted in the form:
"date and time created %s %s by %s", <date>, <time>, <login>

where <date> is expressed in the format of the date utility's %y/%m/%d conversion specification, <time> in the format of the date utility's %T conversion specification format, and <login> is the login name of the user creating the file. 🎀

  • -m mrlist — Insert the list of modification request (MR) numbers into the SCCS file as the reason for creating the initial delta, in a manner identical to delta. The application shall ensure that the v flag is set and the MR numbers are validated if the v flag has a value (the name of an MR number validation program). A diagnostic message shall be written if the v flag is not set or MR validation fails.
  • -h — Check the structure of the SCCS file and compare the newly computed checksum with the checksum stored in the SCCS file. If the newly computed checksum does not match the checksum in the SCCS file, a diagnostic message shall be written. 🔍
  • -z — Recompute the SCCS file checksum and store it in the first line of the SCCS file (see the -h option above).
Okay bestie, real talk: note that use of this option on a truly corrupted file may prevent future detection of the corruption. Like, you'd be covering up the crime scene. 💀

🦋 OPERANDS 🦋

These operands shall be supported:

  • file — A pathname of an existing SCCS file or a directory. If file is a directory, the admin utility shall behave as though each file in the directory were specified as a named file — except that non-SCCS files (last component of the pathname does not begin with s.) and unreadable files shall be silently ignored. No drama, no error message, just vibes.
  • newfile — A pathname of an SCCS file to be created. ✨

If exactly one file or newfile operand appears, and it is '-', the standard input shall be read; each line of the standard input shall be taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall be silently ignored. 🌸

💜 STDIN 💜

The standard input shall be a text file, used only if -i is specified without an option-argument or if a file or newfile operand is specified as '-'.

⚠️ Heads up though: if the first character of any standard input line is <SOH> in the POSIX locale, the results are unspecified. So like… don't do that. 🙈

🌸 INPUT FILES 🌸

The SCCS files that already exist? Bestie, they're text files, and their format is unspecified. That's it, that's the tea.

The application has to make sure that the file named by the -i option's name option-argument is a text file, okay? And if the first character of any line in this file is <SOH> in the POSIX locale, then the results are unspecified — like, nobody knows what happens, don't do it, it's giving chaos. 🙈

And if this file has more than 99999 lines, then the number of lines recorded in the header for this file shall be 99999 for this delta. That's the cap. The line counter said no more. 💅

✨ ENVIRONMENT VARIABLES ✨

These little guys below affect how admin runs, so pay attention bestie:

  • LANG — provides a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.) Basically the fallback queen 👑
  • LC_ALL — if it's set to a non-empty string value, it overrides the values of all the other internationalization variables. It's the main character, no cap.
  • LC_CTYPE — determines the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments and input files). Byte-to-character translation vibes. 🦋
  • LC_MESSAGES — determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and the contents of the default -y comment. Yes, your error messages AND your default comment get the locale glow-up.
  • NLSPATH — determines the location of message catalogs for the processing of LC_MESSAGES. It's the map to where the message catalogs live. 🗺️

💤 ASYNCHRONOUS EVENTS 💤

Default. Nothing special, nothing extra, just default. Periodt.

📭 STDOUT 📭

Not used. Literally not used. She doesn't speak here.

😭 STDERR 😭

The standard error shall be used only for diagnostic messages. That's its whole job, and it does it well.

🎀 OUTPUT FILES 🎀

Any SCCS files created shall be text files of an unspecified format — same mysterious energy as the input ones.

During processing of a file, a locking z-file, as described in get, may be created and deleted. So if you see a z-file pop in and out of existence, that's not a glitch, that's the lock doing its thing. 🔥

🌈 EXTENDED DESCRIPTION 🌈

None. Nothing here. Empty. Void. Moving on. 💀

👑 EXIT STATUS 👑

The following exit values shall be returned:

  • 0 — successful completion. Slay. ✨
  • >0 — an error occurred. Oh no. 😭

💀 CONSEQUENCES OF ERRORS 💀

Default.

The following sections are informative.

💖 APPLICATION USAGE 💖

Okay so here's the recommendation, and honestly it's just good hygiene:

It is recommended that directories containing SCCS files be writable by the owner only, and that the SCCS files themselves be read-only. The mode of the directories should allow only the owner to modify SCCS files contained in the directories. The mode of the SCCS files prevents any modification at all except by SCCS commands. Protect your files like they're your notes app, bestie. 🫶

🍓 EXAMPLES 🍓

None. No examples today. The vibes are purely theoretical.

🧚 RATIONALE 🧚

None.

⭐ FUTURE DIRECTIONS ⭐

None.

🦋 SEE ALSO 🦋

  • delta
  • get
  • prs
  • what

The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

And that's a wrap on the whole page, bestie!! 🎀 This iconic lil manual is brought to you by IEEE/The Open Group, 2017, and its official glow-up name is ADMIN(1POSIX). Go forth and version your files responsibly. Mwah. 💅✨

📦 where this page comes from