~sircmpwn/ctools

ac28f2c154d3bb0d69c7cc66a50205de53284dfc — Drew DeVault 2 years ago 65643b8
Initial pass on documentation
M README.md => README.md +8 -0
@@ 35,6 35,14 @@ Alternatively, you can compile all of the tools with meson:
This is recommended when packaging ctools for meson-supported systems. Some
options are available when building with meson, consult meson_options.txt.

## Documentation

Man pages are provided via [scdoc](https://git.sr.ht/~sircmpwn/scdoc) and may be
found in the `doc` directory. If using meson and scdoc is installed, man pages
are built and installed by default. Note that a manual reader is not provided by
ctools, though the `man` command must do something useful for your system to be
considered POSIX compatible.

## Conformance tests

Build with meson and run `ninja -C build test` to run POSIX conformance tests

A doc/basename.1.scd => doc/basename.1.scd +39 -0
@@ 0,0 1,39 @@
basename(1) "ctools"

# NAME

basename - print the filename part of a pathname

# SYNOPSIS

*basename* _string_ [suffix]

# DESCRIPTION

*basename* will interpret _string_ as a pathname and print only the filename
portion of the path. If a suffix is specified on the command line and is found
to be the suffix of the filename, it will be trimmed.

# UNSPECIFIED BEHAVIOR

The POSIX standard does not unambiguously specify the behavior of this command
under certain conditions. Under such conditions, the ctools implementation of
*basename* behaves as follows:

- If _string_ is an empty string, *basename* will randomly choose between
  printing "." or an empty string.
- If _string_ is equal to "//", *basename* may randomly choose to output it
  as-is with no further processing.

# DISCLAIMER

This command is part of ctools and is compatible with POSIX-1.2017, and may
optionally support XSI extensions. This man page is not intended to be a
complete reference, and where it disagrees with the specification, the
specification takes precedence.

# AUTHORS

ctools is maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other
open source contributors. Up-to-date sources and information may be found at
https://git.sr.ht/~sircmpwn/ctools.

A doc/cat.1.scd => doc/cat.1.scd +35 -0
@@ 0,0 1,35 @@
cat(1) "ctools"

# NAME

cat - concatenate files

# SYNOPSIS

*cat* [-u] [_file_...]

# DESCRIPTION

*cat* will read and copy each specified file to _stdout_ in order. If no files
are specified, or "-" is specified, cat will read from _stdin_ instead of a
named file.

# OPTIONS

*-u*
	According to the standard, this option will ostensibly "write bytes from
	the input file to the standard output without delay as each is read",
	but in practice is ignored by the ctools implementation.

# DISCLAIMER

This command is part of ctools and is compatible with POSIX-1.2017, and may
optionally support XSI extensions. This man page is not intended to be a
complete reference, and where it disagrees with the specification, the
specification takes precedence.

# AUTHORS

ctools is maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other
open source contributors. Up-to-date sources and information may be found at
https://git.sr.ht/~sircmpwn/ctools.

A doc/chgrp.1.scd => doc/chgrp.1.scd +71 -0
@@ 0,0 1,71 @@
chgrp(1) "ctools"

# NAME

chgrp - change group ownership of files

# SYNOPSIS

*chgrp* [<-h | -R [-H|-L|-P]>] _group_ _file_...

# DESCRIPTION

*chgrp* will update the group ownership of each _file_ specified to the
requested _group_, if the user has sufficient permissions.

# OPTIONS

*-h*
	Each _file_ specified which is a symbolic link will have the symbolic
	link's ownership updated, rather than the link target.

*-R*
	Descend into any directories specified on the command line and apply
	ownership changes to their children, recursively.

*-H*
	When a symlink which refers to a directory is specified on the command
	line, *chgrp* will update the directory it refers to rather than the
	symlink itself, as well as all of its children, recursively.

*-L*
	When a symlink which refers to a directory is specified on the command
	line or encountered while *chgrp* recursivly descends the filesystem,
	*chgrp* will update the directory it refers to rather than the symlink
	itself, as well as all of its children, recursively.

*-P*
	When a symlink which refers to a directory is specified on the command
	line or encountered while *chgrp* recursivly descends the filesystem,
	*chgrp* will update the ownership of the symlink itself and will not
	update the target or any of its children.

The *-h* option is mutually incompatible with the *-R* option. The *-H*, *-L*,
and *-P* options have no effect unless *-R* is also specified.

# UNSPECIFIED BEHAVIOR

The POSIX standard does not unambiguously specify the behavior of this command
under certain conditions. Under such conditions, the ctools implementation of
*chgrp* behaves as follows:

- If *-R* is specified but not any option between *-H*, *-L*, and *-P*, one of
  these options will be chosen randomly as the default behavior.

# NOTES

If an error occurs, *chgrp* will exit with a status code >0. If an error occurs
partway through processing, a subset of the files will have been updated.

# DISCLAIMER

This command is part of ctools and is compatible with POSIX-1.2017, and may
optionally support XSI extensions. This man page is not intended to be a
complete reference, and where it disagrees with the specification, the
specification takes precedence.

# AUTHORS

ctools is maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other
open source contributors. Up-to-date sources and information may be found at
https://git.sr.ht/~sircmpwn/ctools.

A doc/chmod.1.scd => doc/chmod.1.scd +120 -0
@@ 0,0 1,120 @@
chmod(1) "ctools"

# NAME

chmod - change the mode of files

# SYNOPSIS

*chmod* [-R] _mode_ _file_...

# DESCRIPTION

*chmod* will update the mode of each _file_ to the specified _mode_, if the user
has sufficient permissions. The _mode_ may be specified in octal or
symbolically.

## OCTAL MODES

If _mode_ is specified as an octal number, the file mode will be set to that
mode.

## SYMBOLIC MODES

A symbolic mode string consists of three parts: who, how, and what to update,
which are concatenated together to form the symbolic mode string.

The "who" part specifies the users affected by the change:

|] u
:[ Update user permissions
|  g
:  Update group permissions
|  o
:  Update owner permissions
|  a
:  Update all permissions

The "who" part may be omitted, in which case *a* is the default.

The "how" part specifies how to apply the change:

|] \+
:[ Add permissions
|  -
:  Remove permissions
|  =
:  Clear permissions

And the "what" part specifies what permissions to update:

|] r
:[ Update read permissions
|  w
:  Update write permissions
|  x
:  Update execute permissions

For example, a symbolic mode of "g+rwx" will allow members of the group whose
group ID corresponds to the gid of the affected file to read, write, and execute
that file. "u=w" will clear the "write" bit of the "user" permissions,
preventing anyone without direct ownership from writing to the file. "-x" will
prevent any user from executing the file. And so on.

In technical terms, the symbolic mode corresponds to bitwise operations
performed against the existing numeric file mode. The "who" part forms a mask,
the "how" part selects an operation, and the "what" part specifies the value to
apply. "g+rwx" will select 777 as the value, mask it with 070 (to affect the
group bits), then perform a bitwise OR with the file's existing mode to
determine the new file mode.

## SPECIAL SYMBOLIC MODES

If "who" includes (or implies) *u* or *g*, and "what" includes *s*, the
set-uid-on-execution or set-gid-on-execution bits (commonly referred to as suid
and sgid) will be affected, respectively.

If "what" is set to X (in uppercase), then all execute bits of any directory
affected will be updated, and any file with at least one execute bit set will
have all execute bits updated.

On systems with XSI support, *t* may be specified in the "what" part to update
the "sticky" bit on directories affected by *chmod*.

# OPTIONS

*-R*
	Descend into any directories specified on the command line and apply
	mode changes to their children, recursively.

# UNSPECIFIED BEHAVIOR

The POSIX standard does not unambiguously specify the behavior of this command
under certain conditions. Under such conditions, the ctools implementation of
*chmod* behaves as follows:

- *chmod* ignores attempts to set the suid or sgid bits of regular files whose
  execute bits would sum to zero after the changes are applied.
- Clearing all execute bits of regular files will randomly clear their setuid
  and setgid bits as well.
- Requests to clear the setuid or setgid bits of files which are not regular
  files are randomly ignored, except in the specific cases of *chmod u-s* or
  *chmod g-s*.

# NOTES

If an error occurs, *chgrp* will exit with a status code >0. If an error occurs
partway through processing, a subset of the files will have been updated.

# DISCLAIMER

This command is part of ctools and is compatible with POSIX-1.2017, and may
optionally support XSI extensions. This man page is not intended to be a
complete reference, and where it disagrees with the specification, the
specification takes precedence.

# AUTHORS

ctools is maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other
open source contributors. Up-to-date sources and information may be found at
https://git.sr.ht/~sircmpwn/ctools.

A doc/false.1.scd => doc/false.1.scd +26 -0
@@ 0,0 1,26 @@
false(1) "ctools"

# NAME

false - exit with status code 1

# SYNOPSIS

*false*

# DESCRIPTION

This program will always exit with status code 1, indicating failure.

# DISCLAIMER

This command is part of ctools and is compatible with POSIX-1.2017, and may
optionally support XSI extensions. This man page is not intended to be a
complete reference, and where it disagrees with the specification, the
specification takes precedence.

# AUTHORS

ctools is maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other
open source contributors. Up-to-date sources and information may be found at
https://git.sr.ht/~sircmpwn/ctools.

A doc/meson.build => doc/meson.build +32 -0
@@ 0,0 1,32 @@
scdoc_prog = find_program(scdoc.get_pkgconfig_variable('scdoc'), native: true)
sh = find_program('sh', native: true)
mandir = get_option('mandir')

man_files = [
	'basename.1',
	'cat.1',
	'chgrp.1',
	'chmod.1',
	'false.1',
	'true.1',
]

foreach page : man_files
	filename = page + '.scd'
	topic = filename.split('.')[-3].split('/')[-1]
	section = filename.split('.')[-2]
	output = '@0@.@1@'.format(topic, section)

	# TODO: Sort out why these get rebuilt every time
	custom_target(
		output,
		input: filename,
		output: output,
		command: [
			sh, '-c', '@0@ < @INPUT@ > @1@'.format(
				scdoc_prog.path(), output)
		],
		install: true,
		install_dir: '@0@/man@1@'.format(mandir, section)
	)
endforeach

A doc/true.1.scd => doc/true.1.scd +26 -0
@@ 0,0 1,26 @@
true(1) "ctools"

# NAME

true - exit with status code 0

# SYNOPSIS

*true*

# DESCRIPTION

This program will always exit with status code 0, indicating success.

# DISCLAIMER

This command is part of ctools and is compatible with POSIX-1.2017, and may
optionally support XSI extensions. This man page is not intended to be a
complete reference, and where it disagrees with the specification, the
specification takes precedence.

# AUTHORS

ctools is maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other
open source contributors. Up-to-date sources and information may be found at
https://git.sr.ht/~sircmpwn/ctools.

M meson.build => meson.build +5 -0
@@ 63,4 63,9 @@ foreach prog : oneshots
	executable(prog, ['src/' + prog + '.c'])
endforeach

scdoc = dependency('scdoc', native: true, required: get_option('man-pages'))
if scdoc.found()
	subdir('doc')
endif

subdir('test')

M meson_options.txt => meson_options.txt +1 -0
@@ 1,1 1,2 @@
option('xsi', type: 'boolean', value: true, description: 'Enable optional XSI support')
option('man-pages', type: 'feature', value: 'auto', description: 'Generate and install man pages')