abort

NAME

ABORT - abort the current transaction

SYNOPSIS

ABORT [ WORK | TRANSACTION ]

DESCRIPTION

ABORT rolls back the current transaction and causes all the updates made by the transaction to be discarded. This command is identical in behavior to the standard SQL command ROLLBACK [rollback(7)], and is present only for historical reasons.

PARAMETERS

WORK
TRANSACTION: Optional key words. They have no effect.

NOTES

Use COMMIT [commit(7)] to successfully terminate a transaction.

Issuing ABORT when not inside a transaction does no harm, but it will provoke a warning message.

EXAMPLES

To abort all changes:

ABORT;

COMPATIBILITY

This command is a PostgreSQL extension present for historical reasons. ROLLBACK is the equivalent standard SQL command.

alter_conversion

NAME

ALTER CONVERSION - change the definition of a conversion

SYNOPSIS

ALTER CONVERSION name RENAME TO newname

DESCRIPTION

ALTER CONVERSION changes the definition of a conversion. The only currently available functionality is to rename the conversion.

PARAMETERS

name: The name (optionally schema-qualified) of an existing conversion.
newname: The new name of the conversion.

EXAMPLES

To rename the conversion iso_8859_1_to_utf_8 to latin1_to_unicode:

ALTER CONVERSION iso_8859_1_to_utf_8 RENAME TO latin1_to_unicode;

COMPATIBILITY

There is no ALTER CONVERSION statement in the SQL standard.

alter_domain

NAME

ALTER DOMAIN - change the definition of a domain

SYNOPSIS

ALTER DOMAIN name { SET DEFAULT expression | DROP DEFAULT } ALTER DOMAIN name { SET | DROP } NOT NULL ALTER DOMAIN name ADD domain_constraint ALTER DOMAIN name DROP CONSTRAINT constraint_name [ RESTRICT | CASCADE ] ALTER DOMAIN name OWNER TO new_owner

DESCRIPTION

ALTER DOMAIN changes the definition of an existing domain. There are several sub-forms:

SET/DROP DEFAULT: These forms set or remove the default value for a domain. Note that defaults only apply to subsequent INSERT commands; they do not affect rows already in a table using the domain.
SET/DROP NOT NULL: These forms change whether a domain is marked to allow NULL values or to reject NULL values. You may only SET NOT NULL when the columns using the domain contain no null values.
ADD domain_constraint: This form adds a new constraint to a domain using the same syntax as CREATE DOMAIN [create_domain(7)]. This will only succeed if all columns using the domain satisfy the new constraint.
DROP CONSTRAINT: This form drops constraints on a domain.
OWNER: This form changes the owner of the domain to the specified user.

You must own the domain to use ALTER DOMAIN; except for ALTER DOMAIN OWNER, which may only be executed by a superuser.

PARAMETERS

name: The name (possibly schema-qualified) of an existing domain to alter.
domain_constraint: New domain constraint for the domain.
constraint_name: Name of an existing constraint to drop.
CASCADE: Automatically drop objects that depend on the constraint.
RESTRICT: Refuse to drop the constraint if there are any dependent objects. This is the default behavior.
new_owner: The user name of the new owner of the domain.

EXAMPLES

To add a NOT NULL constraint to a domain:

ALTER DOMAIN zipcode SET NOT NULL;

To remove a NOT NULL constraint from a domain:

ALTER DOMAIN zipcode DROP NOT NULL;

To add a check constraint to a domain:

ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5);

To remove a check constraint from a domain:

ALTER DOMAIN zipcode DROP CONSTRAINT zipchk;

COMPATIBILITY

The ALTER DOMAIN statement is compatible with SQL99, except for the OWNER variant, which is a PostgreSQL extension.

alter_group

NAME

ALTER GROUP - change a user group

SYNOPSIS

ALTER GROUP groupname ADD USER username [, ... ] ALTER GROUP groupname DROP USER username [, ... ] ALTER GROUP groupname RENAME TO newname

DESCRIPTION

ALTER GROUP is used to change a user group. The first two variants add or remove users from a group. Only database superusers can use this command. Adding a user to a group does not create the user. Similarly, removing a user from a group does not drop the user itself.

The third variant changes the name of the group. Only a database superuser can rename groups.

PARAMETERS

groupname: The name of the group to modify.
username: Users which are to be added or removed from the group. The users must exist.
newname: The new name of the group.

EXAMPLES

Add users to a group:

ALTER GROUP staff ADD USER karl, john;

Remove a user from a group:

ALTER GROUP workers DROP USER beth;

COMPATIBILITY

There is no ALTER GROUP statement in the SQL standard. The concept of roles is similar.

alter_operator_class

NAME

ALTER OPERATOR CLASS - change the definition of an operator class

SYNOPSIS

ALTER OPERATOR CLASS name USING index_method RENAME TO newname

DESCRIPTION

ALTER OPERATOR CLASS changes the definition of an operator class. The only functionality is to rename the operator class.

PARAMETERS

name: The name (optionally schema-qualified) of an existing operator class.
index_method: The name of the index method this operator class is for.
newname: The new name of the operator class.

COMPATIBILITY

There is no ALTER OPERATOR CLASS statement in the SQL standard.

alter_sequence

NAME

ALTER SEQUENCE - alter the definition of a sequence generator

SYNOPSIS

ALTER SEQUENCE name [ INCREMENT [ BY ] increment ] [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ] [ RESTART [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ]

DESCRIPTION

ALTER SEQUENCE changes the parameters of an existing sequence generator. Any parameter not specifically set in the ALTER SEQUENCE command retains its prior setting.

PARAMETERS

name: The name (optionally schema-qualified) of a sequence to be altered.
increment: The clause INCREMENT BY increment is optional. A positive value will make an ascending sequence, a negative one a descending sequence. If unspecified, the old increment value will be maintained.
minvalue
NO MINVALUE: The optional clause MINVALUE minvalue determines the minimum value a sequence can generate. If NO MINVALUE is specified, the defaults of 1 and -263-1 for ascending and descending sequences, respectively, will be used. If neither option is specified, the current minimum value will be maintained.
maxvalue
NO MAXVALUE: The optional clause MAXVALUE maxvalue determines the maximum value for the sequence. If NO MAXVALUE is specified, the defaults are 263-1 and -1 for ascending and descending sequences, respectively, will be used. If neither option is specified, the current maximum value will be maintained.
start: The optional clause RESTART WITH start changes the current value of the sequence.
cache: The clause CACHE cache enables sequence numbers to be preallocated and stored in memory for faster access. The minimum value is 1 (only one value can be generated at a time, i.e., no cache). If unspecified, the old cache value will be maintained.
CYCLE: The optional CYCLE key word may be used to enable the sequence to wrap around when the maxvalue or minvalue has been reached by an ascending or descending sequence respectively. If the limit is reached, the next number generated will be the minvalue or maxvalue, respectively.
NO CYCLE: If the optional NO CYCLE key word is specified, any calls to nextval after the sequence has reached its maximum value will return an error. If neither CYCLE or NO CYCLE are specified, the old cycle behaviour will be maintained.

EXAMPLES

Restart a sequence called serial, at 105:

ALTER SEQUENCE serial RESTART WITH 105;

NOTES

To avoid blocking of concurrent transactions that obtain numbers from the same sequence, ALTER SEQUENCE is never rolled back; the changes take effect immediately and are not reversible.

ALTER SEQUENCE will not immediately affect nextval results in backends, other than the current one, that have preallocated (cached) sequence values. They will use up all cached values prior to noticing the changed sequence parameters. The current backend will be affected immediately.

COMPATIBILITY

SQL99

ALTER SEQUENCE is a PostgreSQL language extension. There is no ALTER SEQUENCE statement in SQL99.

alter_trigger

NAME

ALTER TRIGGER - change the definition of a trigger

SYNOPSIS

ALTER TRIGGER name ON table RENAME TO newname

DESCRIPTION

ALTER TRIGGER changes properties of an existing trigger. The RENAME clause changes the name of the given trigger without otherwise changing the trigger definition.

You must own the table on which the trigger acts to be allowed to change its properties.

PARAMETERS

name: The name of an existing trigger to alter.
table: The name of the table on which this trigger acts.
newname: The new name for the trigger.

EXAMPLES

To rename an existing trigger:

ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs;

COMPATIBILITY

ALTER TRIGGER is a PostgreSQL extension of the SQL standard.

analyze

NAME

ANALYZE - collect statistics about a database

SYNOPSIS

ANALYZE [ VERBOSE ] [ table [ (column [, ...] ) ] ]

DESCRIPTION

ANALYZE collects statistics about the contents of tables in the database, and stores the results in the system table pg_statistic. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries.

With no parameter, ANALYZE examines every table in the current database. With a parameter, ANALYZE examines only that table. It is further possible to give a list of column names, in which case only the statistics for those columns are collected.

PARAMETERS

VERBOSE: Enables display of progress messages.
table: The name (possibly schema-qualified) of a specific table to analyze. Defaults to all tables in the current database.
column: The name of a specific column to analyze. Defaults to all columns.

OUTPUTS

When VERBOSE is specified, ANALYZE emits progress messages to indicate which table is currently being processed. Various statistics about the tables are printed as well.

NOTES

It is a good idea to run ANALYZE periodically, or just after making major changes in the contents of a table. Accurate statistics will help the planner to choose the most appropriate query plan, and thereby improve the speed of query processing. A common strategy is to run VACUUM [vacuum(7)] and ANALYZE once a day during a low-usage time of day.

Unlike VACUUM FULL, ANALYZE requires only a read lock on the target table, so it can run in parallel with other activity on the table.

The statistics collected by ANALYZE usually include a list of some of the most common values in each column and a histogram showing the approximate data distribution in each column. One or both of these may be omitted if ANALYZE deems them uninteresting (for example, in a unique-key column, there are no common values) or if the column data type does not support the appropriate operators. There is more information about the statistics in the chapter called ``Routine Database Maintenance`` in the documentation.

For large tables, ANALYZE takes a random sample of the table contents, rather than examining every row. This allows even very large tables to be analyzed in a small amount of time. Note, however, that the statistics are only approximate, and will change slightly each time ANALYZE is run, even if the actual table contents did not change. This may result in small changes in the planner`s estimated costs shown by EXPLAIN. In rare situations, this non-determinism will cause the query optimizer to choose a different query plan between runs of ANALYZE. To avoid this, raise the amount of statistics collected by ANALYZE, as described below.

The extent of analysis can be controlled by adjusting the DEFAULT_STATISTICS_TARGET parameter variable, or on a column-by-column basis by setting the per-column statistics target with ALTER TABLE ... ALTER COLUMN ... SET STATISTICS (see ALTER TABLE [alter_table(7)]). The target value sets the maximum number of entries in the most-common-value list and the maximum number of bins in the histogram. The default target value is 10, but this can be adjusted up or down to trade off accuracy of planner estimates against the time taken for ANALYZE and the amount of space occupied in pg_statistic. In particular, setting the statistics target to zero disables collection of statistics for that column. It may be useful to do that for columns that are never used as part of the WHERE, GROUP BY, or ORDER BY clauses of queries, since the planner will have no use for statistics on such columns.

The largest statistics target among the columns being analyzed determines the number of table rows sampled to prepare the statistics. Increasing the target causes a proportional increase in the time and space needed to do ANALYZE.

COMPATIBILITY

There is no ANALYZE statement in the SQL standard.

ascii

NAME

ascii - the ASCII character set encoded in octal, decimal, and hexadecimal

DESCRIPTION

ASCII is the American Standard Code for Information Interchange. It is a 7-bit code. Many 8-bit codes (such as ISO 8859-1, the Linux default character set) contain ASCII as their lower half. The international counterpart of ASCII is known as ISO 646.

The following table contains the 128 ASCII characters.

C program `X` escapes are noted.

Oct	Dec	Hex	Char	Oct	Dec	Hex	Char

000	0	00	NUL ``	100	64	40	@
001	1	01	SOH	101	65	41	A
002	2	02	STX	102	66	42	B
003	3	03	ETX	103	67	43	C
004	4	04	EOT	104	68	44	D
005	5	05	ENQ	105	69	45	E
006	6	06	ACK	106	70	46	F
007	7	07	BEL `a`	107	71	47	G
010	8	08	BS ``	110	72	48	H
011	9	09	HT ` `	111	73	49	I
012	10	0A	LF ` `	112	74	4A	J
013	11	0B	VT `v`	113	75	4B	K
014	12	0C	FF `f`	114	76	4C	L
015	13	0D	CR ` `	115	77	4D	M
016	14	0E	SO	116	78	4E	N
017	15	0F	SI	117	79	4F	O
020	16	10	DLE	120	80	50	P
021	17	11	DC1	121	81	51	Q
022	18	12	DC2	122	82	52	R
023	19	13	DC3	123	83	53	S
024	20	14	DC4	124	84	54	T
025	21	15	NAK	125	85	55	U
026	22	16	SYN	126	86	56	V
027	23	17	ETB	127	87	57	W
030	24	18	CAN	130	88	58	X
031	25	19	EM	131	89	59	Y
032	26	1A	SUB	132	90	5A	Z
033	27	1B	ESC	133	91	5B	[
034	28	1C	FS	134	92	5C	`\`
035	29	1D	GS	135	93	5D	]
036	30	1E	RS	136	94	5E	^
037	31	1F	US	137	95	5F	_
040	32	20	SPACE	140	96	60	`
041	33	21	!	141	97	61	a
042	34	22	"	142	98	62	b
043	35	23	#	143	99	63	c
044	36	24	$	144	100	64	d
045	37	25	%	145	101	65	e
046	38	26	&	146	102	66	f
047	39	27	`	147	103	67	g
050	40	28	(	150	104	68	h
051	41	29	)	151	105	69	i
052	42	2A	*	152	106	6A	j
053	43	2B	+	153	107	6B	k
054	44	2C	,	154	108	6C	l
055	45	2D	-	155	109	6D	m
056	46	2E	.	156	110	6E	n
057	47	2F	/	157	111	6F	o
060	48	30	0	160	112	70	p
061	49	31	1	161	113	71	q
062	50	32	2	162	114	72	r
063	51	33	3	163	115	73	s
064	52	34	4	164	116	74	t
065	53	35	5	165	117	75	u
066	54	36	6	166	118	76	v
067	55	37	7	167	119	77	w
070	56	38	8	170	120	78	x
071	57	39	9	171	121	79	y
072	58	3A	:	172	122	7A	z
073	59	3B	;	173	123	7B	{
074	60	3C	<	174	124	7C	\|
075	61	3D	=	175	125	7D	}
076	62	3E	>	176	126	7E	~
077	63	3F	?	177	127	7F	DEL

HISTORY

An ascii manual page appeared in Version 7 of AT&T UNIX.

On older terminals, the underscore code is displayed as a left arrow, called backarrow, the caret is displayed as an up-arrow and the vertical bar has a hole in the middle.

Uppercase and lowercase characters differ by just one bit and the ASCII character 2 differs from the double quote by just one bit, too. That made it much easier to encode characters mechanically or with a non-microcontroller-based electronic keyboard and that pairing was found on old teletypes.

The ASCII standard was published by the United States of America Standards Institute (USASI) in 1968.

TABLES

For convenience, let us give more compact tables in hex and decimal.

2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120 ------------- --------------------------------- 0: 0 @ P ` p 0: ( 2 < F P Z d n x 1: ! 1 A Q a q 1: ) 3 = G Q [ e o y 2: " 2 B R b r 2: * 4 > H R f p z 3: # 3 C S c s 3: ! + 5 ? I S ] g q { 4: $ 4 D T d t 4: " , 6 @ J T ^ h r | 5: % 5 E U e u 5: # - 7 A K U _ i s } 6: & 6 F V f v 6: $ . 8 B L V ` j t ~ 7: ` 7 G W g w 7: % / 9 C M W a k u DEL 8: ( 8 H X h x 8: & 0 : D N X b l v 9: ) 9 I Y i y 9: ` 1 ; E O Y c m w A: * : J Z j z B: + ; K [ k { C: , < L l | D: - = M ] m } E: . > N ^ n ~ F: / ? O _ o DEL

authdaemon

NAME

authlib - Courier Authentication Library

SYNOPSIS

authpam command [ arg ... ]

authpwd command [ arg ... ]

authshadow command [ arg ... ]

authuserdb command [ arg ... ]

authvchkpw command [ arg ... ]

authcram command [ arg ... ]

authmysql command [ arg ... ]

authpgsql command [ arg ... ]

authldap command [ arg ... ]

authdaemon command [ arg ... ]

authcustom command [ arg ... ]

authdaemond [ start | stop | restart ]

DESCRIPTION

This library is used for two purposes:

1. Read an E-mail address that is supposed to be for a local account. Determine the local account`s home directory, and system userid and groupid.

2. Read a login id and a password. If valid, determine the account`s home directory, system userid, and groupid.

The term "authentication" is used in the following documentation to refer to either one of these two functions. The library contains several alternative authentication implementations, that may be selected at runtime.

authdaemon: authenticates through a background daemon proxy. This is now the installation default. Unless otherwise specified, the authdaemon module will always be installed. authdaemon is installed instead of the other authentication modules. Those modules are instead compiled into a separate executable program, authdaemond that is initialized at system start, and runs in the background. The authdaemon authentication module forwards the authentication requests to authdaemond, which forwards the authentication request to the real authentication module, and the result of the request is eventually returned back to the application. Because the real authentication process runs as a persistent background process, it is possible for the authentication process to open and hold permanent connections to the back-end authentication database (be it an LDAP directory, a MySQL or a PostgreSQL server), instead of connecting and disconnecting for every request. Obviously, this tremendously improves the authentication performance.
authpam: authenticates using the system`s PAM library (pluggable authentication module). This is, essentially, a way to use existing PAM modules for authentication functionality. Note, however, that the authenticated account`s home directory, userid and groupid are still read from the /etc/passwd file, since PAM functionality is limited to validating account passwords.
authpwd: authenticates from the /etc/passwd file.
authshadow: like authpwd except passwords are read from /etc/shadow.
authuserdb: authenticates against the userdb(8) database.
authvchkpw: supports existing vpopmail/vchkpw virtual domains.
authcram: authenticates against the userdb(8) database using the challenge/response authentication mechanism (CRAM), instead of the traditional userid/password.
authmysql: authenticates against a list of mail accounts stored in an external MySQL database. The /etc/courier-imap/authmysqlrc configuration file defines the particular details regarding the MySQL database and the schema of the mail account list table.
authpgsql: authenticates against a list of mail accounts stored in an external PostgreSQL database. The authpgsqlrc configuration file defines the particular details regarding the PostgreSQL database and the schema of the mail account list table.
authldap: authenticates against a list of mail accounts stored in an external LDAP directory. The configuration file defines the particular details regarding the LDAP directory layout.
authcustom: this is a stub where custom authentication code can be added. This authentication module is just a stub that doesn`t really do anything. It`s purpose is to serve as a placeholder where custom authentication code can be easily added.

This is a complete list of available authentication modules. The actual installed authentication modules are determined by the resources on the server. For example, the authmysql authentication module will be installed only if the system provides MySQL support libraries.

AUTHDAEMON AUTHENTICATION MODULE

The following command must be executed from the system startup script in order for the authdaemon module to work (and remember that authdaemon is installed by default:

/usr/lib/courier-imap/authlib/authdaemond start

"authdaemond stop" should also be added to the system shutdown script.

The /var/lib/courier-imap/authdaemon subdirectory must be created in advance. This directory will have the filesystem socket used for interprocess communication between authdaemon and authdaemond. It goes without saying that the underlying filesystem for /var/lib/courier-imap/authdaemon must support filesystem domain sockets. This pretty much excludes all network filesystems, so this directory should reside on a local disk.

/var/lib/courier-imap/authdaemon MUST NOT HAVE any world-readable, executable or writable permissions! Under NO circumstances should this be allowed to happen. The exact permissions and ownership of /var/lib/courier-imap/authdaemon varies. For the standalone versions of Courier-IMAP and SqWebMail, /var/lib/courier-imap/authdaemon should be owned by root, and have no group or world permissions. For the Courier mail server, /var/lib/courier-imap/authdaemon should be owned by the userid that Courier is installed under, and it must be readable and writable by the Courier user and group (but no world permissions).

CONFIGURING AUTHDAEMOND

The /etc/courier-imap/authdaemonrc configuration file sets several operational parameters for the authdaemond process. See the comments in the default file installed for more information. Currently, /etc/courier-imap/authdaemonrc sets two parameters: number of daemon processes, and authentication modules/process that will be used.

Although authdaemond might include several authentication modules, not all of them may be used. This makes it possible to install the same authdaemond build on multiple systems with different authentication needs. The default module list specified in /etc/courier-imap/authdaemonrc would be a list of all the available authentication modules.

/usr/lib/courier-imap/authlib/authdaemond is actually a very short shell script that executes the real authdaemond program. The available programs are authdaemond.plain, authdaemond.ldap, authdaemond.mysql, and authdaemond.pgsql. The "plain" program contains all the authentication modules except for authldap, authmysql, and authpgsql. The "ldap" program includes all the authentication modules in "plain", plus authldap Ditto for the "mysql" and "pgsql" processes.

This arrangement allows convenient creation of pre-configured binary packages. The authdaemond shell script runs authdaemond.plain only if none of the other processes are installed on the system. First, it checks if authdaemond.ldap, authdaemond.mysql, or authdaemond.pgsql is installed. If not, authdaemond.plain is brought up. This makes it possible to prepare a basic binary package that provides only basic authentication services and does not require either LDAP, MySQL, or PostgreSQL runtime support on the server. If either of these authentication requirements are needed, a separate binary sub-package will load the appropriate authdaemond process.

Note that it is not possible to use both LDAP and MySQL, for example, authentication at the same time. That`s because their support is in different authdaemond processes, and only one authdaemond process can run at the same time. If both (or all three non-plain processes) are installed, the authdaemond script picks either the first one it finds, or whatever is explicitly specified in the /etc/courier-imap/authdaemonrc configuration file.

The number of authdaemond processes is also set in this configuration file. The more processes that are started, the more authentication requests can be handled. If authdaemon does not receive an answer within a moderate amount of time, it will declare an authentication failure, and abort. Try increasing the number of processes if you start seeing random authentication failures. However, that should only be used as a stop-gap measure. If the default number of authdaemond processes proves to be insufficient, it is far more likely that more resources are needed for the server: more RAM, a faster disk, or a faster CPU, at least in the humble opinion of the author. Increasing the number of processes should only be used as a stop-gap measure, until a more thorough analysis on the bottleneck can be made.

/usr/lib/courier-imap/authlib/authdaemond restart

Run the above command after making any changes to /etc/courier-imap/authdaemonrc. "authdaemond restart" is required for any changes to take effect.

AUTHENTICATION PROTOCOL

The rest of this documentation describes the internal protocol used by this authentication library. It is only of interest to developers who wish to extend the authentication library to support a custom authentication module, or a derived extension to an existing module.

The original implementation of this authentication library used small, self-contained, binary programs, named for their authentication module: authldap, authpam, and others. Later, the authdaemon module came about, which wrapped the other authentication modules into a separate background daemon process, which communicated with the authdaemon module. The authdaemon module is now always enabled by default, but it is still possible to build and install each authentication module as a self-contained binary program. Note, however, that applications such as SqWebMail, and Courier link directly with all the authentication modules, and will not use external modules for authentication.

authdaemon came about as a direct result of technical issues that prevented SqWebMail and Courier from using external binary modules. authdaemond is really nothing more than a simple application that links directly with the authentication modules, and talks to the authdaemon authentication module that follows this authentication protocol.

STAND-ALONE AUTHENTICATION MODULES

This section describes the authentication protocol for self-contained authentication modules. Although the default configuration no longer uses self-contained modules, the stand-alone protocol serves as a foundation for the protocol used by authentication modules as part of the authdaemond authentication process, or when they are linked directly with the application that uses this authentication library.

Here`s the typical way that stand-alone authentication modules are used:

1. A list of authentication modules are read from a configuration file. Multiple authentication modules could be available, but not all of them are required in most situations.

2. The application executes the following command:

LOGIN AUTHMODULE1 AUTHMODULE2 ... APP

LOGIN is a full pathname to an application that reads the authentication information, such as the userid and a password. Arguments to LOGIN are full pathnames to each authentication module (if there are more than one), followed by a full pathname to the main application.

3. LOGIN reads the userid and password, then runs the program specified by its first argument, which is the first authentication module. The remaining arguments are passed to the new process. The mechanism by which the authentication information is passed to the authentication module is described later.

4. Each authentication module reads the authentication information, and determines if the previous authentication module succesfully processed the authentication request. If not, the module attempts to authenticate it itself. In any event, the module runs the next program specified by its first argument, and the remaining arguments are passed along to the next program. If any previous authentication module succesfully processed the authentication request, the next program is run immediately without any further processing.

5. Eventually, APP runs, APP reads the authentication information and determines whether any authentication module managed to succesfully process the authentication request. If so, APP runs normally. Otherwise, APP runs LOGIN with its original arguments in order to return an error message ("Password invalid", or something similar) and read the next authentication request.

Daisy-chaining authentication modules, in this fashion, makes it possible to have hybrid systems that use multiple authentication modules. Example: using authpam to authenticate system accounts, and authmysql to authentication virtual mailboxes without a corresponding system account.

Here`s a more detailed description of the overall process:

THE LOGIN PROCESS

The LOGIN process checks if the AUTHARGC environment variable is set. If not, this is the first time the LOGIN process comes up, and LOGIN displays the initial login prompt. Additionally, the command line arguments to LOGIN are literal copied to the AUTHARGC and AUTHARGVn environment variables. That is: the number of command line arguments is saved in AUTHARGC; the zeroth command line argument is saved in AUTHARGV0; the remaining command line arguments are saved in AUTHARGV1, AUTHARGV2, and so on.

After obtaining the authentication information (such as the userid and password), LOGIN creates a pipe, and arranges for the output end of the pipe to be located on file descriptor #3. The LOGIN process forks; the original process then executes the first authentication module, in the manner described earlier; the child process writes the authentication record to the pipe, then terminates.

The authentication record is a chunk of data in the following format:

: SERVICE<NEWLINE>AUTHTYPE<NEWLINE>AUTHDATA

Each occurence of <NEWLINE> represents an ASCII linefeed character (#10). "SERVICE" identifies the service that originates the authentication request, such as "imap", or "webmail". Authentication module may use this identifier, or ignore it.

"AUTHTYPE" identifies the format of the authentication request. Everything after the second <NEWLINE> is an opaque blob of data, whose format is determined by AUTHTYPE.

: Note: There`s a theoretical upper limit on the maximum size of the authentication record. It is high enough not to matter in most situations (the total number of characters allowed cannot be more than 8189 characters on a typical GNU/Linux system).

The following AUTHTYPE formats are currently defined:

login: A typical userid/password authentication request. AUTHDATA contains the following data: userid<NEWLINE>password<NEWLINE>.
cram-md5: Specifies the CRAM-MD5 authentication request. AUTHDATA contains the following data: challenge<NEWLINE>response<NEWLINE>. The "challenge" and "response" strings are base64-encoded.
cram-sha1: Specifies the CRAM-SHA1 authentication request, instead of CRAM-MD5, and uses the same format for AUTHDATA.

THE AUTHENTICATION MODULE

The first thing an authentication module does is check if the environment variable AUTHENTICATED is set to a non-empty string. If so, it means that a previous authentication module has handled the authentication request, so this module simply runs the next program, specified by the first argument to this authentication module.

Otherwise, the authentication module reads the authentication record from file descriptor #3, and determines whether it wants to try this authentication record. If not, the module creates a new pipe, arranges the output of the pipe to be on file descriptor #3, forks, the parent process runs the next authentication module, and the child process writes the authentication record to the pipe, then exits.

There are two ways to handle an authentication request: 1) Use the AUTHARGC and AUTHARGVn variables to restart the entire authentication process - this is used in the event it is determined that the authentication request must be failed, or 2) run the next daisy-changed module, in the manner described previously, when it is determined that another authentication module can attempt to try to handle this request.

The following action occurs when the authentication module succesfully validates an authentication request:

1. The authenticated login ID is saved in the AUTHENTICATED environment variable.

2. The process`s userid and groupid are reset to the corresponding userid and groupid of the authenticated login id, and the current directory is set to the process`s defined home directory.

3. Some additional environment variables may also be initialized: AUTHFULLNAME - the login ID`s full name; MAILDIR - the login ID`s default maildir mailbox; MAILDIRQUOTA - the requested maildir quota.

THE APPLICATION PROCESS

Eventually, APP runs. The process closes file descriptor #3 (if it`s open, and ignores the error if file descriptor #3 does not exist). If the AUTHENTICATED environment variable is set, it must mean that an authentication module was able to handle this authentication request, so APP starts up and runs normally. Otherwise the original command is reconstructed from the AUTHARGC and AUTHARGVn variables, and the initial login process runs again.

LIBRARY FUNCTIONS

This authentication library provides several convenient functions which can be used to quickly create a compliant login process, and its corresponding application. The login process should be structured as follows:

A SAMPLE LOGIN PROCESS

int main(int argc, char **argv) { if (authmoduser(argc, argv, TIMEOUT, ERR_TIMEOUT)) { /* Print initial greeting here */ } else { /* Error: invalid userid/password */ } /* read userid and password */ authmod(argc-1, argv+1, SERVICE, AUTHTYPE, AUTHDATA); }

The authmoduser function takes care of copying the command line parameters to their corresponding environment variables, and checking whether or not this is the initial time this process runs, or if it is running again after a failed authentication process. TIMEOUT specifies the absolute login timeout, authmoduser quietly terminates the process if it runs due to a failed authentication request and at least TIMEOUT seconds have elapsed since the first time authmoduser was run. ERR_TIMEOUT specifies the number of seconds that authmoduser will sleep after a failed authentication request.

The SERVICE, AUTHTYPE, and AUTHDATA arguments to authmod are null-terminated character strings that form the authentication request. authmod takes care of setting up the pipe to the first authentication module, and runs it.

The application process is even simpler:

A SAMPLE APP PROCESS

int main(int argc, char **argv) { const char *loginid=authmodclient(); /* Application begins normally */ }

The authmodclient function returns the authenticated login ID. If the authentication request failed, authmodclient reruns the original login process, and doesn`t return.

INSIDE AN AUTHENTICATION MODULES

An authentication module needs to define the following structure:

STRUCT AUTHSTATICINFO

struct authstaticinfo { const char *auth_name; char * (*auth_func)(const char *, const char *, char *, int, void (*)(struct authinfo *, void *), void *); int (*auth_prefunc)(const char *, const char *, int (*)(struct authinfo *, void *), void *); void (*auth_cleanupfunc)(); int (*auth_changepwd)(const char *, /* service */ const char *, /* userid */ const char *, /* oldpassword */ const char *); /* new password */ } ;

auth_func points to a function that handles the authentication request. If succesful, auth_func is responsible for resetting the userid and groupid, changing to the authentication account`s home directory, and setting up the necessary environment variables. The first three arguments to auth_func will be SERVICE, AUTHTYPE, and AUTHDATA. The next argument is a boolean flag which is non-zero if the authentication code is being called in the context of a stand-alone authentication module, or zero if the authentication code is called directly by an application. The fifth argument points is a callback function pointer, which may be NULL. If it`s not null, auth_func should not reset the userid, groupid, or the home directory of this process, but should instead initialize the authinfo structure, which is defined as follows:

STRUCT AUTHINFO

struct authinfo { const char *sysusername; const uid_t *sysuserid; gid_t sysgroupid; const char *homedir; const char *address; /* The E-mail address */ const char *fullname; /* gecos, etc... */ const char *maildir; const char *quota; const char *passwd; const char *clearpasswd; /* For authldap */ unsigned staticindex; /* When statically-linked functions are ** called, this holds the index of the ** authentication module in authstaticlist */ } ;

The passwd, clearpasswd, and staticindex fields are not used by auth_func. Either sysusername or sysuserid must be a non-NULL pointer. sysuserid specifies an explicit userid, otherwise sysusername is looked up in the password file.

The last argument to auth_func is an opaque pointer that gets passed as the second argument to the callback function.

auth_func should return a pointer to the authenticated loginid, in dynamic memory (the memory should be free()ed after user. A NULL return indicates an authentication failure. The authentication module should set errno to EPERM in the event that it the next authentication module should have a chance to process the authentication request, or use any other errno value to immediately fail the authentication request, and rerun the original login process.

LINKED AUTHENTICATION MODULES

The auth_prefunc, auth_cleanupfunc, and auth_changepwd functions are not used by stand-alone modules, but when the authentication module is directly linked with an application.

auth_prefunc verifies that the requested userid exists. No passwords are validated, the first two arguments to auth_prefunc are the userid, and SERVICE. auth_prefunc should initialize an authinfo structure, and run the callback function, the third argument to auth_prefunc. The callback function receives the fourth argument to auth_prefunc as an opaque pointer.

auth_prefunc should come back with the callback function`s return code, if the requested userid was found. Otherwise, auth_prefunc should return a non-zero integer. A positive integer should be return in the event that this authentication request should be stopped, and a negative itneger if another authentication module can be tried. An application that links against this authentication library will run each configured authentication module`s auth_prefunc, until some module is able to process the requested userid, or until auth_prefunc comes back with a non-zero positive return code.

auth_func or auth_prefunc might allocate some internal resources, which should be freed by calling auth_cleanupfunc.

The auth_changepwd function is called to implement the change password functionality.

OTHER AUTHENTICATION LIBRARY FUNCTION

This authentication library contains several functions and macros that can be helpful in building authentication modules.

TURNING AUTH_FUNC INTO A MODULE

#define MODULE auth_func #include "mod.h"

mod.h contains template code that reads an authentication request from the previous authentication module, call auth_func, in such a manner, and appropriately run the next module in the authentication chain.

The auth.h header file also declares several useful functions that authentication-related code may find convenient.

BUILDING AUTHDAEMOND

This authentication library builds alternate versions of the authdaemond background process. Some authentication modules have dependencies on external libraries, such as authldap, authmysql, and authpgsql. The authentication library prepares separate versions of authdaemond for each authentication module with a dependency. Each one of these authdaemond versions will also include all other authentication modules that do not have dependencies.

The authentication module configuration for each authdaemond is set in the authdaemond.versions file. A new authentication module will have to be added to authdaemond.versions (potentially creating another authdaemond build). The configure script must be run after making any changes to authdaemond.versions.

FILES

/etc/courier-imap/authmodulelist - list of authentication modules read by applications that directly link with authlib

/etc/courier-imap/authdaemonrc - authdaemond configuration file

/etc/courier-imap/authldaprc - authldap configuration file

/etc/courier-imap/authmysqlrc - authmysql configuration file

/etc/courier-imap/authpgsqlrc - authpgsql configuration file

authldap

NAME

authlib - Courier Authentication Library

SYNOPSIS

authpam command [ arg ... ]

authpwd command [ arg ... ]

authshadow command [ arg ... ]

authuserdb command [ arg ... ]

authvchkpw command [ arg ... ]

authcram command [ arg ... ]

authmysql command [ arg ... ]

authpgsql command [ arg ... ]

authldap command [ arg ... ]

authdaemon command [ arg ... ]

authcustom command [ arg ... ]

authdaemond [ start | stop | restart ]

DESCRIPTION

This library is used for two purposes:

1. Read an E-mail address that is supposed to be for a local account. Determine the local account`s home directory, and system userid and groupid.

2. Read a login id and a password. If valid, determine the account`s home directory, system userid, and groupid.

The term "authentication" is used in the following documentation to refer to either one of these two functions. The library contains several alternative authentication implementations, that may be selected at runtime.

authdaemon: authenticates through a background daemon proxy. This is now the installation default. Unless otherwise specified, the authdaemon module will always be installed. authdaemon is installed instead of the other authentication modules. Those modules are instead compiled into a separate executable program, authdaemond that is initialized at system start, and runs in the background. The authdaemon authentication module forwards the authentication requests to authdaemond, which forwards the authentication request to the real authentication module, and the result of the request is eventually returned back to the application. Because the real authentication process runs as a persistent background process, it is possible for the authentication process to open and hold permanent connections to the back-end authentication database (be it an LDAP directory, a MySQL or a PostgreSQL server), instead of connecting and disconnecting for every request. Obviously, this tremendously improves the authentication performance.
authpam: authenticates using the system`s PAM library (pluggable authentication module). This is, essentially, a way to use existing PAM modules for authentication functionality. Note, however, that the authenticated account`s home directory, userid and groupid are still read from the /etc/passwd file, since PAM functionality is limited to validating account passwords.
authpwd: authenticates from the /etc/passwd file.
authshadow: like authpwd except passwords are read from /etc/shadow.
authuserdb: authenticates against the userdb(8) database.
authvchkpw: supports existing vpopmail/vchkpw virtual domains.
authcram: authenticates against the userdb(8) database using the challenge/response authentication mechanism (CRAM), instead of the traditional userid/password.
authmysql: authenticates against a list of mail accounts stored in an external MySQL database. The /etc/courier-imap/authmysqlrc configuration file defines the particular details regarding the MySQL database and the schema of the mail account list table.
authpgsql: authenticates against a list of mail accounts stored in an external PostgreSQL database. The authpgsqlrc configuration file defines the particular details regarding the PostgreSQL database and the schema of the mail account list table.
authldap: authenticates against a list of mail accounts stored in an external LDAP directory. The configuration file defines the particular details regarding the LDAP directory layout.
authcustom: this is a stub where custom authentication code can be added. This authentication module is just a stub that doesn`t really do anything. It`s purpose is to serve as a placeholder where custom authentication code can be easily added.

This is a complete list of available authentication modules. The actual installed authentication modules are determined by the resources on the server. For example, the authmysql authentication module will be installed only if the system provides MySQL support libraries.

AUTHDAEMON AUTHENTICATION MODULE

The following command must be executed from the system startup script in order for the authdaemon module to work (and remember that authdaemon is installed by default:

/usr/lib/courier-imap/authlib/authdaemond start

"authdaemond stop" should also be added to the system shutdown script.

The /var/lib/courier-imap/authdaemon subdirectory must be created in advance. This directory will have the filesystem socket used for interprocess communication between authdaemon and authdaemond. It goes without saying that the underlying filesystem for /var/lib/courier-imap/authdaemon must support filesystem domain sockets. This pretty much excludes all network filesystems, so this directory should reside on a local disk.

/var/lib/courier-imap/authdaemon MUST NOT HAVE any world-readable, executable or writable permissions! Under NO circumstances should this be allowed to happen. The exact permissions and ownership of /var/lib/courier-imap/authdaemon varies. For the standalone versions of Courier-IMAP and SqWebMail, /var/lib/courier-imap/authdaemon should be owned by root, and have no group or world permissions. For the Courier mail server, /var/lib/courier-imap/authdaemon should be owned by the userid that Courier is installed under, and it must be readable and writable by the Courier user and group (but no world permissions).

CONFIGURING AUTHDAEMOND

The /etc/courier-imap/authdaemonrc configuration file sets several operational parameters for the authdaemond process. See the comments in the default file installed for more information. Currently, /etc/courier-imap/authdaemonrc sets two parameters: number of daemon processes, and authentication modules/process that will be used.

Although authdaemond might include several authentication modules, not all of them may be used. This makes it possible to install the same authdaemond build on multiple systems with different authentication needs. The default module list specified in /etc/courier-imap/authdaemonrc would be a list of all the available authentication modules.

/usr/lib/courier-imap/authlib/authdaemond is actually a very short shell script that executes the real authdaemond program. The available programs are authdaemond.plain, authdaemond.ldap, authdaemond.mysql, and authdaemond.pgsql. The "plain" program contains all the authentication modules except for authldap, authmysql, and authpgsql. The "ldap" program includes all the authentication modules in "plain", plus authldap Ditto for the "mysql" and "pgsql" processes.

This arrangement allows convenient creation of pre-configured binary packages. The authdaemond shell script runs authdaemond.plain only if none of the other processes are installed on the system. First, it checks if authdaemond.ldap, authdaemond.mysql, or authdaemond.pgsql is installed. If not, authdaemond.plain is brought up. This makes it possible to prepare a basic binary package that provides only basic authentication services and does not require either LDAP, MySQL, or PostgreSQL runtime support on the server. If either of these authentication requirements are needed, a separate binary sub-package will load the appropriate authdaemond process.

Note that it is not possible to use both LDAP and MySQL, for example, authentication at the same time. That`s because their support is in different authdaemond processes, and only one authdaemond process can run at the same time. If both (or all three non-plain processes) are installed, the authdaemond script picks either the first one it finds, or whatever is explicitly specified in the /etc/courier-imap/authdaemonrc configuration file.

The number of authdaemond processes is also set in this configuration file. The more processes that are started, the more authentication requests can be handled. If authdaemon does not receive an answer within a moderate amount of time, it will declare an authentication failure, and abort. Try increasing the number of processes if you start seeing random authentication failures. However, that should only be used as a stop-gap measure. If the default number of authdaemond processes proves to be insufficient, it is far more likely that more resources are needed for the server: more RAM, a faster disk, or a faster CPU, at least in the humble opinion of the author. Increasing the number of processes should only be used as a stop-gap measure, until a more thorough analysis on the bottleneck can be made.

/usr/lib/courier-imap/authlib/authdaemond restart

Run the above command after making any changes to /etc/courier-imap/authdaemonrc. "authdaemond restart" is required for any changes to take effect.

AUTHENTICATION PROTOCOL

The rest of this documentation describes the internal protocol used by this authentication library. It is only of interest to developers who wish to extend the authentication library to support a custom authentication module, or a derived extension to an existing module.

The original implementation of this authentication library used small, self-contained, binary programs, named for their authentication module: authldap, authpam, and others. Later, the authdaemon module came about, which wrapped the other authentication modules into a separate background daemon process, which communicated with the authdaemon module. The authdaemon module is now always enabled by default, but it is still possible to build and install each authentication module as a self-contained binary program. Note, however, that applications such as SqWebMail, and Courier link directly with all the authentication modules, and will not use external modules for authentication.

authdaemon came about as a direct result of technical issues that prevented SqWebMail and Courier from using external binary modules. authdaemond is really nothing more than a simple application that links directly with the authentication modules, and talks to the authdaemon authentication module that follows this authentication protocol.

STAND-ALONE AUTHENTICATION MODULES

This section describes the authentication protocol for self-contained authentication modules. Although the default configuration no longer uses self-contained modules, the stand-alone protocol serves as a foundation for the protocol used by authentication modules as part of the authdaemond authentication process, or when they are linked directly with the application that uses this authentication library.

Here`s the typical way that stand-alone authentication modules are used:

1. A list of authentication modules are read from a configuration file. Multiple authentication modules could be available, but not all of them are required in most situations.

2. The application executes the following command:

LOGIN AUTHMODULE1 AUTHMODULE2 ... APP

LOGIN is a full pathname to an application that reads the authentication information, such as the userid and a password. Arguments to LOGIN are full pathnames to each authentication module (if there are more than one), followed by a full pathname to the main application.

3. LOGIN reads the userid and password, then runs the program specified by its first argument, which is the first authentication module. The remaining arguments are passed to the new process. The mechanism by which the authentication information is passed to the authentication module is described later.

4. Each authentication module reads the authentication information, and determines if the previous authentication module succesfully processed the authentication request. If not, the module attempts to authenticate it itself. In any event, the module runs the next program specified by its first argument, and the remaining arguments are passed along to the next program. If any previous authentication module succesfully processed the authentication request, the next program is run immediately without any further processing.

5. Eventually, APP runs, APP reads the authentication information and determines whether any authentication module managed to succesfully process the authentication request. If so, APP runs normally. Otherwise, APP runs LOGIN with its original arguments in order to return an error message ("Password invalid", or something similar) and read the next authentication request.

Daisy-chaining authentication modules, in this fashion, makes it possible to have hybrid systems that use multiple authentication modules. Example: using authpam to authenticate system accounts, and authmysql to authentication virtual mailboxes without a corresponding system account.

Here`s a more detailed description of the overall process:

THE LOGIN PROCESS

The LOGIN process checks if the AUTHARGC environment variable is set. If not, this is the first time the LOGIN process comes up, and LOGIN displays the initial login prompt. Additionally, the command line arguments to LOGIN are literal copied to the AUTHARGC and AUTHARGVn environment variables. That is: the number of command line arguments is saved in AUTHARGC; the zeroth command line argument is saved in AUTHARGV0; the remaining command line arguments are saved in AUTHARGV1, AUTHARGV2, and so on.

After obtaining the authentication information (such as the userid and password), LOGIN creates a pipe, and arranges for the output end of the pipe to be located on file descriptor #3. The LOGIN process forks; the original process then executes the first authentication module, in the manner described earlier; the child process writes the authentication record to the pipe, then terminates.

The authentication record is a chunk of data in the following format:

: SERVICE<NEWLINE>AUTHTYPE<NEWLINE>AUTHDATA

Each occurence of <NEWLINE> represents an ASCII linefeed character (#10). "SERVICE" identifies the service that originates the authentication request, such as "imap", or "webmail". Authentication module may use this identifier, or ignore it.

"AUTHTYPE" identifies the format of the authentication request. Everything after the second <NEWLINE> is an opaque blob of data, whose format is determined by AUTHTYPE.

: Note: There`s a theoretical upper limit on the maximum size of the authentication record. It is high enough not to matter in most situations (the total number of characters allowed cannot be more than 8189 characters on a typical GNU/Linux system).

The following AUTHTYPE formats are currently defined:

login: A typical userid/password authentication request. AUTHDATA contains the following data: userid<NEWLINE>password<NEWLINE>.
cram-md5: Specifies the CRAM-MD5 authentication request. AUTHDATA contains the following data: challenge<NEWLINE>response<NEWLINE>. The "challenge" and "response" strings are base64-encoded.
cram-sha1: Specifies the CRAM-SHA1 authentication request, instead of CRAM-MD5, and uses the same format for AUTHDATA.

THE AUTHENTICATION MODULE

The first thing an authentication module does is check if the environment variable AUTHENTICATED is set to a non-empty string. If so, it means that a previous authentication module has handled the authentication request, so this module simply runs the next program, specified by the first argument to this authentication module.

Otherwise, the authentication module reads the authentication record from file descriptor #3, and determines whether it wants to try this authentication record. If not, the module creates a new pipe, arranges the output of the pipe to be on file descriptor #3, forks, the parent process runs the next authentication module, and the child process writes the authentication record to the pipe, then exits.

There are two ways to handle an authentication request: 1) Use the AUTHARGC and AUTHARGVn variables to restart the entire authentication process - this is used in the event it is determined that the authentication request must be failed, or 2) run the next daisy-changed module, in the manner described previously, when it is determined that another authentication module can attempt to try to handle this request.

The following action occurs when the authentication module succesfully validates an authentication request:

1. The authenticated login ID is saved in the AUTHENTICATED environment variable.

2. The process`s userid and groupid are reset to the corresponding userid and groupid of the authenticated login id, and the current directory is set to the process`s defined home directory.

3. Some additional environment variables may also be initialized: AUTHFULLNAME - the login ID`s full name; MAILDIR - the login ID`s default maildir mailbox; MAILDIRQUOTA - the requested maildir quota.

THE APPLICATION PROCESS

Eventually, APP runs. The process closes file descriptor #3 (if it`s open, and ignores the error if file descriptor #3 does not exist). If the AUTHENTICATED environment variable is set, it must mean that an authentication module was able to handle this authentication request, so APP starts up and runs normally. Otherwise the original command is reconstructed from the AUTHARGC and AUTHARGVn variables, and the initial login process runs again.

LIBRARY FUNCTIONS

This authentication library provides several convenient functions which can be used to quickly create a compliant login process, and its corresponding application. The login process should be structured as follows:

A SAMPLE LOGIN PROCESS

int main(int argc, char **argv) { if (authmoduser(argc, argv, TIMEOUT, ERR_TIMEOUT)) { /* Print initial greeting here */ } else { /* Error: invalid userid/password */ } /* read userid and password */ authmod(argc-1, argv+1, SERVICE, AUTHTYPE, AUTHDATA); }

The authmoduser function takes care of copying the command line parameters to their corresponding environment variables, and checking whether or not this is the initial time this process runs, or if it is running again after a failed authentication process. TIMEOUT specifies the absolute login timeout, authmoduser quietly terminates the process if it runs due to a failed authentication request and at least TIMEOUT seconds have elapsed since the first time authmoduser was run. ERR_TIMEOUT specifies the number of seconds that authmoduser will sleep after a failed authentication request.

The SERVICE, AUTHTYPE, and AUTHDATA arguments to authmod are null-terminated character strings that form the authentication request. authmod takes care of setting up the pipe to the first authentication module, and runs it.

The application process is even simpler:

A SAMPLE APP PROCESS

int main(int argc, char **argv) { const char *loginid=authmodclient(); /* Application begins normally */ }

The authmodclient function returns the authenticated login ID. If the authentication request failed, authmodclient reruns the original login process, and doesn`t return.

INSIDE AN AUTHENTICATION MODULES

An authentication module needs to define the following structure:

STRUCT AUTHSTATICINFO

struct authstaticinfo { const char *auth_name; char * (*auth_func)(const char *, const char *, char *, int, void (*)(struct authinfo *, void *), void *); int (*auth_prefunc)(const char *, const char *, int (*)(struct authinfo *, void *), void *); void (*auth_cleanupfunc)(); int (*auth_changepwd)(const char *, /* service */ const char *, /* userid */ const char *, /* oldpassword */ const char *); /* new password */ } ;

auth_func points to a function that handles the authentication request. If succesful, auth_func is responsible for resetting the userid and groupid, changing to the authentication account`s home directory, and setting up the necessary environment variables. The first three arguments to auth_func will be SERVICE, AUTHTYPE, and AUTHDATA. The next argument is a boolean flag which is non-zero if the authentication code is being called in the context of a stand-alone authentication module, or zero if the authentication code is called directly by an application. The fifth argument points is a callback function pointer, which may be NULL. If it`s not null, auth_func should not reset the userid, groupid, or the home directory of this process, but should instead initialize the authinfo structure, which is defined as follows:

STRUCT AUTHINFO

struct authinfo { const char *sysusername; const uid_t *sysuserid; gid_t sysgroupid; const char *homedir; const char *address; /* The E-mail address */ const char *fullname; /* gecos, etc... */ const char *maildir; const char *quota; const char *passwd; const char *clearpasswd; /* For authldap */ unsigned staticindex; /* When statically-linked functions are ** called, this holds the index of the ** authentication module in authstaticlist */ } ;

The passwd, clearpasswd, and staticindex fields are not used by auth_func. Either sysusername or sysuserid must be a non-NULL pointer. sysuserid specifies an explicit userid, otherwise sysusername is looked up in the password file.

The last argument to auth_func is an opaque pointer that gets passed as the second argument to the callback function.

auth_func should return a pointer to the authenticated loginid, in dynamic memory (the memory should be free()ed after user. A NULL return indicates an authentication failure. The authentication module should set errno to EPERM in the event that it the next authentication module should have a chance to process the authentication request, or use any other errno value to immediately fail the authentication request, and rerun the original login process.

LINKED AUTHENTICATION MODULES

The auth_prefunc, auth_cleanupfunc, and auth_changepwd functions are not used by stand-alone modules, but when the authentication module is directly linked with an application.

auth_prefunc verifies that the requested userid exists. No passwords are validated, the first two arguments to auth_prefunc are the userid, and SERVICE. auth_prefunc should initialize an authinfo structure, and run the callback function, the third argument to auth_prefunc. The callback function receives the fourth argument to auth_prefunc as an opaque pointer.

auth_prefunc should come back with the callback function`s return code, if the requested userid was found. Otherwise, auth_prefunc should return a non-zero integer. A positive integer should be return in the event that this authentication request should be stopped, and a negative itneger if another authentication module can be tried. An application that links against this authentication library will run each configured authentication module`s auth_prefunc, until some module is able to process the requested userid, or until auth_prefunc comes back with a non-zero positive return code.

auth_func or auth_prefunc might allocate some internal resources, which should be freed by calling auth_cleanupfunc.

The auth_changepwd function is called to implement the change password functionality.

OTHER AUTHENTICATION LIBRARY FUNCTION

This authentication library contains several functions and macros that can be helpful in building authentication modules.

TURNING AUTH_FUNC INTO A MODULE

#define MODULE auth_func #include "mod.h"

mod.h contains template code that reads an authentication request from the previous authentication module, call auth_func, in such a manner, and appropriately run the next module in the authentication chain.

The auth.h header file also declares several useful functions that authentication-related code may find convenient.

BUILDING AUTHDAEMOND

This authentication library builds alternate versions of the authdaemond background process. Some authentication modules have dependencies on external libraries, such as authldap, authmysql, and authpgsql. The authentication library prepares separate versions of authdaemond for each authentication module with a dependency. Each one of these authdaemond versions will also include all other authentication modules that do not have dependencies.

The authentication module configuration for each authdaemond is set in the authdaemond.versions file. A new authentication module will have to be added to authdaemond.versions (potentially creating another authdaemond build). The configure script must be run after making any changes to authdaemond.versions.

FILES

/etc/courier-imap/authmodulelist - list of authentication modules read by applications that directly link with authlib

/etc/courier-imap/authdaemonrc - authdaemond configuration file

/etc/courier-imap/authldaprc - authldap configuration file

/etc/courier-imap/authmysqlrc - authmysql configuration file

/etc/courier-imap/authpgsqlrc - authpgsql configuration file

authmysql

NAME

authlib - Courier Authentication Library

SYNOPSIS

authpam command [ arg ... ]

authpwd command [ arg ... ]

authshadow command [ arg ... ]

authuserdb command [ arg ... ]

authvchkpw command [ arg ... ]

authcram command [ arg ... ]

authmysql command [ arg ... ]

authpgsql command [ arg ... ]

authldap command [ arg ... ]

authdaemon command [ arg ... ]

authcustom command [ arg ... ]

authdaemond [ start | stop | restart ]

DESCRIPTION

This library is used for two purposes:

1. Read an E-mail address that is supposed to be for a local account. Determine the local account`s home directory, and system userid and groupid.

2. Read a login id and a password. If valid, determine the account`s home directory, system userid, and groupid.

The term "authentication" is used in the following documentation to refer to either one of these two functions. The library contains several alternative authentication implementations, that may be selected at runtime.

authdaemon: authenticates through a background daemon proxy. This is now the installation default. Unless otherwise specified, the authdaemon module will always be installed. authdaemon is installed instead of the other authentication modules. Those modules are instead compiled into a separate executable program, authdaemond that is initialized at system start, and runs in the background. The authdaemon authentication module forwards the authentication requests to authdaemond, which forwards the authentication request to the real authentication module, and the result of the request is eventually returned back to the application. Because the real authentication process runs as a persistent background process, it is possible for the authentication process to open and hold permanent connections to the back-end authentication database (be it an LDAP directory, a MySQL or a PostgreSQL server), instead of connecting and disconnecting for every request. Obviously, this tremendously improves the authentication performance.
authpam: authenticates using the system`s PAM library (pluggable authentication module). This is, essentially, a way to use existing PAM modules for authentication functionality. Note, however, that the authenticated account`s home directory, userid and groupid are still read from the /etc/passwd file, since PAM functionality is limited to validating account passwords.
authpwd: authenticates from the /etc/passwd file.
authshadow: like authpwd except passwords are read from /etc/shadow.
authuserdb: authenticates against the userdb(8) database.
authvchkpw: supports existing vpopmail/vchkpw virtual domains.
authcram: authenticates against the userdb(8) database using the challenge/response authentication mechanism (CRAM), instead of the traditional userid/password.
authmysql: authenticates against a list of mail accounts stored in an external MySQL database. The /etc/courier-imap/authmysqlrc configuration file defines the particular details regarding the MySQL database and the schema of the mail account list table.
authpgsql: authenticates against a list of mail accounts stored in an external PostgreSQL database. The authpgsqlrc configuration file defines the particular details regarding the PostgreSQL database and the schema of the mail account list table.
authldap: authenticates against a list of mail accounts stored in an external LDAP directory. The configuration file defines the particular details regarding the LDAP directory layout.
authcustom: this is a stub where custom authentication code can be added. This authentication module is just a stub that doesn`t really do anything. It`s purpose is to serve as a placeholder where custom authentication code can be easily added.

This is a complete list of available authentication modules. The actual installed authentication modules are determined by the resources on the server. For example, the authmysql authentication module will be installed only if the system provides MySQL support libraries.

AUTHDAEMON AUTHENTICATION MODULE

The following command must be executed from the system startup script in order for the authdaemon module to work (and remember that authdaemon is installed by default:

/usr/lib/courier-imap/authlib/authdaemond start

"authdaemond stop" should also be added to the system shutdown script.

The /var/lib/courier-imap/authdaemon subdirectory must be created in advance. This directory will have the filesystem socket used for interprocess communication between authdaemon and authdaemond. It goes without saying that the underlying filesystem for /var/lib/courier-imap/authdaemon must support filesystem domain sockets. This pretty much excludes all network filesystems, so this directory should reside on a local disk.

/var/lib/courier-imap/authdaemon MUST NOT HAVE any world-readable, executable or writable permissions! Under NO circumstances should this be allowed to happen. The exact permissions and ownership of /var/lib/courier-imap/authdaemon varies. For the standalone versions of Courier-IMAP and SqWebMail, /var/lib/courier-imap/authdaemon should be owned by root, and have no group or world permissions. For the Courier mail server, /var/lib/courier-imap/authdaemon should be owned by the userid that Courier is installed under, and it must be readable and writable by the Courier user and group (but no world permissions).

CONFIGURING AUTHDAEMOND

The /etc/courier-imap/authdaemonrc configuration file sets several operational parameters for the authdaemond process. See the comments in the default file installed for more information. Currently, /etc/courier-imap/authdaemonrc sets two parameters: number of daemon processes, and authentication modules/process that will be used.

Although authdaemond might include several authentication modules, not all of them may be used. This makes it possible to install the same authdaemond build on multiple systems with different authentication needs. The default module list specified in /etc/courier-imap/authdaemonrc would be a list of all the available authentication modules.

/usr/lib/courier-imap/authlib/authdaemond is actually a very short shell script that executes the real authdaemond program. The available programs are authdaemond.plain, authdaemond.ldap, authdaemond.mysql, and authdaemond.pgsql. The "plain" program contains all the authentication modules except for authldap, authmysql, and authpgsql. The "ldap" program includes all the authentication modules in "plain", plus authldap Ditto for the "mysql" and "pgsql" processes.

This arrangement allows convenient creation of pre-configured binary packages. The authdaemond shell script runs authdaemond.plain only if none of the other processes are installed on the system. First, it checks if authdaemond.ldap, authdaemond.mysql, or authdaemond.pgsql is installed. If not, authdaemond.plain is brought up. This makes it possible to prepare a basic binary package that provides only basic authentication services and does not require either LDAP, MySQL, or PostgreSQL runtime support on the server. If either of these authentication requirements are needed, a separate binary sub-package will load the appropriate authdaemond process.

Note that it is not possible to use both LDAP and MySQL, for example, authentication at the same time. That`s because their support is in different authdaemond processes, and only one authdaemond process can run at the same time. If both (or all three non-plain processes) are installed, the authdaemond script picks either the first one it finds, or whatever is explicitly specified in the /etc/courier-imap/authdaemonrc configuration file.

The number of authdaemond processes is also set in this configuration file. The more processes that are started, the more authentication requests can be handled. If authdaemon does not receive an answer within a moderate amount of time, it will declare an authentication failure, and abort. Try increasing the number of processes if you start seeing random authentication failures. However, that should only be used as a stop-gap measure. If the default number of authdaemond processes proves to be insufficient, it is far more likely that more resources are needed for the server: more RAM, a faster disk, or a faster CPU, at least in the humble opinion of the author. Increasing the number of processes should only be used as a stop-gap measure, until a more thorough analysis on the bottleneck can be made.

/usr/lib/courier-imap/authlib/authdaemond restart

Run the above command after making any changes to /etc/courier-imap/authdaemonrc. "authdaemond restart" is required for any changes to take effect.

AUTHENTICATION PROTOCOL

The rest of this documentation describes the internal protocol used by this authentication library. It is only of interest to developers who wish to extend the authentication library to support a custom authentication module, or a derived extension to an existing module.

The original implementation of this authentication library used small, self-contained, binary programs, named for their authentication module: authldap, authpam, and others. Later, the authdaemon module came about, which wrapped the other authentication modules into a separate background daemon process, which communicated with the authdaemon module. The authdaemon module is now always enabled by default, but it is still possible to build and install each authentication module as a self-contained binary program. Note, however, that applications such as SqWebMail, and Courier link directly with all the authentication modules, and will not use external modules for authentication.

authdaemon came about as a direct result of technical issues that prevented SqWebMail and Courier from using external binary modules. authdaemond is really nothing more than a simple application that links directly with the authentication modules, and talks to the authdaemon authentication module that follows this authentication protocol.

STAND-ALONE AUTHENTICATION MODULES

This section describes the authentication protocol for self-contained authentication modules. Although the default configuration no longer uses self-contained modules, the stand-alone protocol serves as a foundation for the protocol used by authentication modules as part of the authdaemond authentication process, or when they are linked directly with the application that uses this authentication library.

Here`s the typical way that stand-alone authentication modules are used:

1. A list of authentication modules are read from a configuration file. Multiple authentication modules could be available, but not all of them are required in most situations.

2. The application executes the following command:

LOGIN AUTHMODULE1 AUTHMODULE2 ... APP

LOGIN is a full pathname to an application that reads the authentication information, such as the userid and a password. Arguments to LOGIN are full pathnames to each authentication module (if there are more than one), followed by a full pathname to the main application.

3. LOGIN reads the userid and password, then runs the program specified by its first argument, which is the first authentication module. The remaining arguments are passed to the new process. The mechanism by which the authentication information is passed to the authentication module is described later.

4. Each authentication module reads the authentication information, and determines if the previous authentication module succesfully processed the authentication request. If not, the module attempts to authenticate it itself. In any event, the module runs the next program specified by its first argument, and the remaining arguments are passed along to the next program. If any previous authentication module succesfully processed the authentication request, the next program is run immediately without any further processing.

5. Eventually, APP runs, APP reads the authentication information and determines whether any authentication module managed to succesfully process the authentication request. If so, APP runs normally. Otherwise, APP runs LOGIN with its original arguments in order to return an error message ("Password invalid", or something similar) and read the next authentication request.

Daisy-chaining authentication modules, in this fashion, makes it possible to have hybrid systems that use multiple authentication modules. Example: using authpam to authenticate system accounts, and authmysql to authentication virtual mailboxes without a corresponding system account.

Here`s a more detailed description of the overall process:

THE LOGIN PROCESS

The LOGIN process checks if the AUTHARGC environment variable is set. If not, this is the first time the LOGIN process comes up, and LOGIN displays the initial login prompt. Additionally, the command line arguments to LOGIN are literal copied to the AUTHARGC and AUTHARGVn environment variables. That is: the number of command line arguments is saved in AUTHARGC; the zeroth command line argument is saved in AUTHARGV0; the remaining command line arguments are saved in AUTHARGV1, AUTHARGV2, and so on.

After obtaining the authentication information (such as the userid and password), LOGIN creates a pipe, and arranges for the output end of the pipe to be located on file descriptor #3. The LOGIN process forks; the original process then executes the first authentication module, in the manner described earlier; the child process writes the authentication record to the pipe, then terminates.

The authentication record is a chunk of data in the following format:

: SERVICE<NEWLINE>AUTHTYPE<NEWLINE>AUTHDATA

Each occurence of <NEWLINE> represents an ASCII linefeed character (#10). "SERVICE" identifies the service that originates the authentication request, such as "imap", or "webmail". Authentication module may use this identifier, or ignore it.

"AUTHTYPE" identifies the format of the authentication request. Everything after the second <NEWLINE> is an opaque blob of data, whose format is determined by AUTHTYPE.

: Note: There`s a theoretical upper limit on the maximum size of the authentication record. It is high enough not to matter in most situations (the total number of characters allowed cannot be more than 8189 characters on a typical GNU/Linux system).

The following AUTHTYPE formats are currently defined:

login: A typical userid/password authentication request. AUTHDATA contains the following data: userid<NEWLINE>password<NEWLINE>.
cram-md5: Specifies the CRAM-MD5 authentication request. AUTHDATA contains the following data: challenge<NEWLINE>response<NEWLINE>. The "challenge" and "response" strings are base64-encoded.
cram-sha1: Specifies the CRAM-SHA1 authentication request, instead of CRAM-MD5, and uses the same format for AUTHDATA.

THE AUTHENTICATION MODULE

The first thing an authentication module does is check if the environment variable AUTHENTICATED is set to a non-empty string. If so, it means that a previous authentication module has handled the authentication request, so this module simply runs the next program, specified by the first argument to this authentication module.

Otherwise, the authentication module reads the authentication record from file descriptor #3, and determines whether it wants to try this authentication record. If not, the module creates a new pipe, arranges the output of the pipe to be on file descriptor #3, forks, the parent process runs the next authentication module, and the child process writes the authentication record to the pipe, then exits.

There are two ways to handle an authentication request: 1) Use the AUTHARGC and AUTHARGVn variables to restart the entire authentication process - this is used in the event it is determined that the authentication request must be failed, or 2) run the next daisy-changed module, in the manner described previously, when it is determined that another authentication module can attempt to try to handle this request.

The following action occurs when the authentication module succesfully validates an authentication request:

1. The authenticated login ID is saved in the AUTHENTICATED environment variable.

2. The process`s userid and groupid are reset to the corresponding userid and groupid of the authenticated login id, and the current directory is set to the process`s defined home directory.

3. Some additional environment variables may also be initialized: AUTHFULLNAME - the login ID`s full name; MAILDIR - the login ID`s default maildir mailbox; MAILDIRQUOTA - the requested maildir quota.

THE APPLICATION PROCESS

Eventually, APP runs. The process closes file descriptor #3 (if it`s open, and ignores the error if file descriptor #3 does not exist). If the AUTHENTICATED environment variable is set, it must mean that an authentication module was able to handle this authentication request, so APP starts up and runs normally. Otherwise the original command is reconstructed from the AUTHARGC and AUTHARGVn variables, and the initial login process runs again.

LIBRARY FUNCTIONS

This authentication library provides several convenient functions which can be used to quickly create a compliant login process, and its corresponding application. The login process should be structured as follows:

A SAMPLE LOGIN PROCESS

int main(int argc, char **argv) { if (authmoduser(argc, argv, TIMEOUT, ERR_TIMEOUT)) { /* Print initial greeting here */ } else { /* Error: invalid userid/password */ } /* read userid and password */ authmod(argc-1, argv+1, SERVICE, AUTHTYPE, AUTHDATA); }

The authmoduser function takes care of copying the command line parameters to their corresponding environment variables, and checking whether or not this is the initial time this process runs, or if it is running again after a failed authentication process. TIMEOUT specifies the absolute login timeout, authmoduser quietly terminates the process if it runs due to a failed authentication request and at least TIMEOUT seconds have elapsed since the first time authmoduser was run. ERR_TIMEOUT specifies the number of seconds that authmoduser will sleep after a failed authentication request.

The SERVICE, AUTHTYPE, and AUTHDATA arguments to authmod are null-terminated character strings that form the authentication request. authmod takes care of setting up the pipe to the first authentication module, and runs it.

The application process is even simpler:

A SAMPLE APP PROCESS

int main(int argc, char **argv) { const char *loginid=authmodclient(); /* Application begins normally */ }

The authmodclient function returns the authenticated login ID. If the authentication request failed, authmodclient reruns the original login process, and doesn`t return.

INSIDE AN AUTHENTICATION MODULES

An authentication module needs to define the following structure:

STRUCT AUTHSTATICINFO

struct authstaticinfo { const char *auth_name; char * (*auth_func)(const char *, const char *, char *, int, void (*)(struct authinfo *, void *), void *); int (*auth_prefunc)(const char *, const char *, int (*)(struct authinfo *, void *), void *); void (*auth_cleanupfunc)(); int (*auth_changepwd)(const char *, /* service */ const char *, /* userid */ const char *, /* oldpassword */ const char *); /* new password */ } ;

auth_func points to a function that handles the authentication request. If succesful, auth_func is responsible for resetting the userid and groupid, changing to the authentication account`s home directory, and setting up the necessary environment variables. The first three arguments to auth_func will be SERVICE, AUTHTYPE, and AUTHDATA. The next argument is a boolean flag which is non-zero if the authentication code is being called in the context of a stand-alone authentication module, or zero if the authentication code is called directly by an application. The fifth argument points is a callback function pointer, which may be NULL. If it`s not null, auth_func should not reset the userid, groupid, or the home directory of this process, but should instead initialize the authinfo structure, which is defined as follows:

STRUCT AUTHINFO

struct authinfo { const char *sysusername; const uid_t *sysuserid; gid_t sysgroupid; const char *homedir; const char *address; /* The E-mail address */ const char *fullname; /* gecos, etc... */ const char *maildir; const char *quota; const char *passwd; const char *clearpasswd; /* For authldap */ unsigned staticindex; /* When statically-linked functions are ** called, this holds the index of the ** authentication module in authstaticlist */ } ;

The passwd, clearpasswd, and staticindex fields are not used by auth_func. Either sysusername or sysuserid must be a non-NULL pointer. sysuserid specifies an explicit userid, otherwise sysusername is looked up in the password file.

The last argument to auth_func is an opaque pointer that gets passed as the second argument to the callback function.

auth_func should return a pointer to the authenticated loginid, in dynamic memory (the memory should be free()ed after user. A NULL return indicates an authentication failure. The authentication module should set errno to EPERM in the event that it the next authentication module should have a chance to process the authentication request, or use any other errno value to immediately fail the authentication request, and rerun the original login process.

LINKED AUTHENTICATION MODULES

The auth_prefunc, auth_cleanupfunc, and auth_changepwd functions are not used by stand-alone modules, but when the authentication module is directly linked with an application.

auth_prefunc verifies that the requested userid exists. No passwords are validated, the first two arguments to auth_prefunc are the userid, and SERVICE. auth_prefunc should initialize an authinfo structure, and run the callback function, the third argument to auth_prefunc. The callback function receives the fourth argument to auth_prefunc as an opaque pointer.

auth_prefunc should come back with the callback function`s return code, if the requested userid was found. Otherwise, auth_prefunc should return a non-zero integer. A positive integer should be return in the event that this authentication request should be stopped, and a negative itneger if another authentication module can be tried. An application that links against this authentication library will run each configured authentication module`s auth_prefunc, until some module is able to process the requested userid, or until auth_prefunc comes back with a non-zero positive return code.

auth_func or auth_prefunc might allocate some internal resources, which should be freed by calling auth_cleanupfunc.

The auth_changepwd function is called to implement the change password functionality.

OTHER AUTHENTICATION LIBRARY FUNCTION

This authentication library contains several functions and macros that can be helpful in building authentication modules.

TURNING AUTH_FUNC INTO A MODULE

#define MODULE auth_func #include "mod.h"

mod.h contains template code that reads an authentication request from the previous authentication module, call auth_func, in such a manner, and appropriately run the next module in the authentication chain.

The auth.h header file also declares several useful functions that authentication-related code may find convenient.

BUILDING AUTHDAEMOND

This authentication library builds alternate versions of the authdaemond background process. Some authentication modules have dependencies on external libraries, such as authldap, authmysql, and authpgsql. The authentication library prepares separate versions of authdaemond for each authentication module with a dependency. Each one of these authdaemond versions will also include all other authentication modules that do not have dependencies.

The authentication module configuration for each authdaemond is set in the authdaemond.versions file. A new authentication module will have to be added to authdaemond.versions (potentially creating another authdaemond build). The configure script must be run after making any changes to authdaemond.versions.

FILES

/etc/courier-imap/authmodulelist - list of authentication modules read by applications that directly link with authlib

/etc/courier-imap/authdaemonrc - authdaemond configuration file

/etc/courier-imap/authldaprc - authldap configuration file

/etc/courier-imap/authmysqlrc - authmysql configuration file

/etc/courier-imap/authpgsqlrc - authpgsql configuration file

authpwd

NAME

authlib - Courier Authentication Library

SYNOPSIS

authpam command [ arg ... ]

authpwd command [ arg ... ]

authshadow command [ arg ... ]

authuserdb command [ arg ... ]

authvchkpw command [ arg ... ]

authcram command [ arg ... ]

authmysql command [ arg ... ]

authpgsql command [ arg ... ]

authldap command [ arg ... ]

authdaemon command [ arg ... ]

authcustom command [ arg ... ]

authdaemond [ start | stop | restart ]

DESCRIPTION

This library is used for two purposes:

1. Read an E-mail address that is supposed to be for a local account. Determine the local account`s home directory, and system userid and groupid.

2. Read a login id and a password. If valid, determine the account`s home directory, system userid, and groupid.

The term "authentication" is used in the following documentation to refer to either one of these two functions. The library contains several alternative authentication implementations, that may be selected at runtime.

authdaemon: authenticates through a background daemon proxy. This is now the installation default. Unless otherwise specified, the authdaemon module will always be installed. authdaemon is installed instead of the other authentication modules. Those modules are instead compiled into a separate executable program, authdaemond that is initialized at system start, and runs in the background. The authdaemon authentication module forwards the authentication requests to authdaemond, which forwards the authentication request to the real authentication module, and the result of the request is eventually returned back to the application. Because the real authentication process runs as a persistent background process, it is possible for the authentication process to open and hold permanent connections to the back-end authentication database (be it an LDAP directory, a MySQL or a PostgreSQL server), instead of connecting and disconnecting for every request. Obviously, this tremendously improves the authentication performance.
authpam: authenticates using the system`s PAM library (pluggable authentication module). This is, essentially, a way to use existing PAM modules for authentication functionality. Note, however, that the authenticated account`s home directory, userid and groupid are still read from the /etc/passwd file, since PAM functionality is limited to validating account passwords.
authpwd: authenticates from the /etc/passwd file.
authshadow: like authpwd except passwords are read from /etc/shadow.
authuserdb: authenticates against the userdb(8) database.
authvchkpw: supports existing vpopmail/vchkpw virtual domains.
authcram: authenticates against the userdb(8) database using the challenge/response authentication mechanism (CRAM), instead of the traditional userid/password.
authmysql: authenticates against a list of mail accounts stored in an external MySQL database. The /etc/courier-imap/authmysqlrc configuration file defines the particular details regarding the MySQL database and the schema of the mail account list table.
authpgsql: authenticates against a list of mail accounts stored in an external PostgreSQL database. The authpgsqlrc configuration file defines the particular details regarding the PostgreSQL database and the schema of the mail account list table.
authldap: authenticates against a list of mail accounts stored in an external LDAP directory. The configuration file defines the particular details regarding the LDAP directory layout.
authcustom: this is a stub where custom authentication code can be added. This authentication module is just a stub that doesn`t really do anything. It`s purpose is to serve as a placeholder where custom authentication code can be easily added.

This is a complete list of available authentication modules. The actual installed authentication modules are determined by the resources on the server. For example, the authmysql authentication module will be installed only if the system provides MySQL support libraries.

AUTHDAEMON AUTHENTICATION MODULE

The following command must be executed from the system startup script in order for the authdaemon module to work (and remember that authdaemon is installed by default:

/usr/lib/courier-imap/authlib/authdaemond start

"authdaemond stop" should also be added to the system shutdown script.

The /var/lib/courier-imap/authdaemon subdirectory must be created in advance. This directory will have the filesystem socket used for interprocess communication between authdaemon and authdaemond. It goes without saying that the underlying filesystem for /var/lib/courier-imap/authdaemon must support filesystem domain sockets. This pretty much excludes all network filesystems, so this directory should reside on a local disk.

/var/lib/courier-imap/authdaemon MUST NOT HAVE any world-readable, executable or writable permissions! Under NO circumstances should this be allowed to happen. The exact permissions and ownership of /var/lib/courier-imap/authdaemon varies. For the standalone versions of Courier-IMAP and SqWebMail, /var/lib/courier-imap/authdaemon should be owned by root, and have no group or world permissions. For the Courier mail server, /var/lib/courier-imap/authdaemon should be owned by the userid that Courier is installed under, and it must be readable and writable by the Courier user and group (but no world permissions).

CONFIGURING AUTHDAEMOND

The /etc/courier-imap/authdaemonrc configuration file sets several operational parameters for the authdaemond process. See the comments in the default file installed for more information. Currently, /etc/courier-imap/authdaemonrc sets two parameters: number of daemon processes, and authentication modules/process that will be used.

Although authdaemond might include several authentication modules, not all of them may be used. This makes it possible to install the same authdaemond build on multiple systems with different authentication needs. The default module list specified in /etc/courier-imap/authdaemonrc would be a list of all the available authentication modules.

/usr/lib/courier-imap/authlib/authdaemond is actually a very short shell script that executes the real authdaemond program. The available programs are authdaemond.plain, authdaemond.ldap, authdaemond.mysql, and authdaemond.pgsql. The "plain" program contains all the authentication modules except for authldap, authmysql, and authpgsql. The "ldap" program includes all the authentication modules in "plain", plus authldap Ditto for the "mysql" and "pgsql" processes.

This arrangement allows convenient creation of pre-configured binary packages. The authdaemond shell script runs authdaemond.plain only if none of the other processes are installed on the system. First, it checks if authdaemond.ldap, authdaemond.mysql, or authdaemond.pgsql is installed. If not, authdaemond.plain is brought up. This makes it possible to prepare a basic binary package that provides only basic authentication services and does not require either LDAP, MySQL, or PostgreSQL runtime support on the server. If either of these authentication requirements are needed, a separate binary sub-package will load the appropriate authdaemond process.

Note that it is not possible to use both LDAP and MySQL, for example, authentication at the same time. That`s because their support is in different authdaemond processes, and only one authdaemond process can run at the same time. If both (or all three non-plain processes) are installed, the authdaemond script picks either the first one it finds, or whatever is explicitly specified in the /etc/courier-imap/authdaemonrc configuration file.

The number of authdaemond processes is also set in this configuration file. The more processes that are started, the more authentication requests can be handled. If authdaemon does not receive an answer within a moderate amount of time, it will declare an authentication failure, and abort. Try increasing the number of processes if you start seeing random authentication failures. However, that should only be used as a stop-gap measure. If the default number of authdaemond processes proves to be insufficient, it is far more likely that more resources are needed for the server: more RAM, a faster disk, or a faster CPU, at least in the humble opinion of the author. Increasing the number of processes should only be used as a stop-gap measure, until a more thorough analysis on the bottleneck can be made.

/usr/lib/courier-imap/authlib/authdaemond restart

Run the above command after making any changes to /etc/courier-imap/authdaemonrc. "authdaemond restart" is required for any changes to take effect.

AUTHENTICATION PROTOCOL

The rest of this documentation describes the internal protocol used by this authentication library. It is only of interest to developers who wish to extend the authentication library to support a custom authentication module, or a derived extension to an existing module.

The original implementation of this authentication library used small, self-contained, binary programs, named for their authentication module: authldap, authpam, and others. Later, the authdaemon module came about, which wrapped the other authentication modules into a separate background daemon process, which communicated with the authdaemon module. The authdaemon module is now always enabled by default, but it is still possible to build and install each authentication module as a self-contained binary program. Note, however, that applications such as SqWebMail, and Courier link directly with all the authentication modules, and will not use external modules for authentication.

authdaemon came about as a direct result of technical issues that prevented SqWebMail and Courier from using external binary modules. authdaemond is really nothing more than a simple application that links directly with the authentication modules, and talks to the authdaemon authentication module that follows this authentication protocol.

STAND-ALONE AUTHENTICATION MODULES

This section describes the authentication protocol for self-contained authentication modules. Although the default configuration no longer uses self-contained modules, the stand-alone protocol serves as a foundation for the protocol used by authentication modules as part of the authdaemond authentication process, or when they are linked directly with the application that uses this authentication library.

Here`s the typical way that stand-alone authentication modules are used:

1. A list of authentication modules are read from a configuration file. Multiple authentication modules could be available, but not all of them are required in most situations.

2. The application executes the following command:

LOGIN AUTHMODULE1 AUTHMODULE2 ... APP

LOGIN is a full pathname to an application that reads the authentication information, such as the userid and a password. Arguments to LOGIN are full pathnames to each authentication module (if there are more than one), followed by a full pathname to the main application.

3. LOGIN reads the userid and password, then runs the program specified by its first argument, which is the first authentication module. The remaining arguments are passed to the new process. The mechanism by which the authentication information is passed to the authentication module is described later.

4. Each authentication module reads the authentication information, and determines if the previous authentication module succesfully processed the authentication request. If not, the module attempts to authenticate it itself. In any event, the module runs the next program specified by its first argument, and the remaining arguments are passed along to the next program. If any previous authentication module succesfully processed the authentication request, the next program is run immediately without any further processing.

5. Eventually, APP runs, APP reads the authentication information and determines whether any authentication module managed to succesfully process the authentication request. If so, APP runs normally. Otherwise, APP runs LOGIN with its original arguments in order to return an error message ("Password invalid", or something similar) and read the next authentication request.

Daisy-chaining authentication modules, in this fashion, makes it possible to have hybrid systems that use multiple authentication modules. Example: using authpam to authenticate system accounts, and authmysql to authentication virtual mailboxes without a corresponding system account.

Here`s a more detailed description of the overall process:

THE LOGIN PROCESS

The LOGIN process checks if the AUTHARGC environment variable is set. If not, this is the first time the LOGIN process comes up, and LOGIN displays the initial login prompt. Additionally, the command line arguments to LOGIN are literal copied to the AUTHARGC and AUTHARGVn environment variables. That is: the number of command line arguments is saved in AUTHARGC; the zeroth command line argument is saved in AUTHARGV0; the remaining command line arguments are saved in AUTHARGV1, AUTHARGV2, and so on.

After obtaining the authentication information (such as the userid and password), LOGIN creates a pipe, and arranges for the output end of the pipe to be located on file descriptor #3. The LOGIN process forks; the original process then executes the first authentication module, in the manner described earlier; the child process writes the authentication record to the pipe, then terminates.

The authentication record is a chunk of data in the following format:

: SERVICE<NEWLINE>AUTHTYPE<NEWLINE>AUTHDATA

Each occurence of <NEWLINE> represents an ASCII linefeed character (#10). "SERVICE" identifies the service that originates the authentication request, such as "imap", or "webmail". Authentication module may use this identifier, or ignore it.

"AUTHTYPE" identifies the format of the authentication request. Everything after the second <NEWLINE> is an opaque blob of data, whose format is determined by AUTHTYPE.

: Note: There`s a theoretical upper limit on the maximum size of the authentication record. It is high enough not to matter in most situations (the total number of characters allowed cannot be more than 8189 characters on a typical GNU/Linux system).

The following AUTHTYPE formats are currently defined:

login: A typical userid/password authentication request. AUTHDATA contains the following data: userid<NEWLINE>password<NEWLINE>.
cram-md5: Specifies the CRAM-MD5 authentication request. AUTHDATA contains the following data: challenge<NEWLINE>response<NEWLINE>. The "challenge" and "response" strings are base64-encoded.
cram-sha1: Specifies the CRAM-SHA1 authentication request, instead of CRAM-MD5, and uses the same format for AUTHDATA.

THE AUTHENTICATION MODULE

The first thing an authentication module does is check if the environment variable AUTHENTICATED is set to a non-empty string. If so, it means that a previous authentication module has handled the authentication request, so this module simply runs the next program, specified by the first argument to this authentication module.

Otherwise, the authentication module reads the authentication record from file descriptor #3, and determines whether it wants to try this authentication record. If not, the module creates a new pipe, arranges the output of the pipe to be on file descriptor #3, forks, the parent process runs the next authentication module, and the child process writes the authentication record to the pipe, then exits.

There are two ways to handle an authentication request: 1) Use the AUTHARGC and AUTHARGVn variables to restart the entire authentication process - this is used in the event it is determined that the authentication request must be failed, or 2) run the next daisy-changed module, in the manner described previously, when it is determined that another authentication module can attempt to try to handle this request.

The following action occurs when the authentication module succesfully validates an authentication request:

1. The authenticated login ID is saved in the AUTHENTICATED environment variable.

2. The process`s userid and groupid are reset to the corresponding userid and groupid of the authenticated login id, and the current directory is set to the process`s defined home directory.

3. Some additional environment variables may also be initialized: AUTHFULLNAME - the login ID`s full name; MAILDIR - the login ID`s default maildir mailbox; MAILDIRQUOTA - the requested maildir quota.

THE APPLICATION PROCESS

Eventually, APP runs. The process closes file descriptor #3 (if it`s open, and ignores the error if file descriptor #3 does not exist). If the AUTHENTICATED environment variable is set, it must mean that an authentication module was able to handle this authentication request, so APP starts up and runs normally. Otherwise the original command is reconstructed from the AUTHARGC and AUTHARGVn variables, and the initial login process runs again.

LIBRARY FUNCTIONS

This authentication library provides several convenient functions which can be used to quickly create a compliant login process, and its corresponding application. The login process should be structured as follows:

A SAMPLE LOGIN PROCESS

int main(int argc, char **argv) { if (authmoduser(argc, argv, TIMEOUT, ERR_TIMEOUT)) { /* Print initial greeting here */ } else { /* Error: invalid userid/password */ } /* read userid and password */ authmod(argc-1, argv+1, SERVICE, AUTHTYPE, AUTHDATA); }

The authmoduser function takes care of copying the command line parameters to their corresponding environment variables, and checking whether or not this is the initial time this process runs, or if it is running again after a failed authentication process. TIMEOUT specifies the absolute login timeout, authmoduser quietly terminates the process if it runs due to a failed authentication request and at least TIMEOUT seconds have elapsed since the first time authmoduser was run. ERR_TIMEOUT specifies the number of seconds that authmoduser will sleep after a failed authentication request.

The SERVICE, AUTHTYPE, and AUTHDATA arguments to authmod are null-terminated character strings that form the authentication request. authmod takes care of setting up the pipe to the first authentication module, and runs it.

The application process is even simpler:

A SAMPLE APP PROCESS

int main(int argc, char **argv) { const char *loginid=authmodclient(); /* Application begins normally */ }

The authmodclient function returns the authenticated login ID. If the authentication request failed, authmodclient reruns the original login process, and doesn`t return.

INSIDE AN AUTHENTICATION MODULES

An authentication module needs to define the following structure:

STRUCT AUTHSTATICINFO

struct authstaticinfo { const char *auth_name; char * (*auth_func)(const char *, const char *, char *, int, void (*)(struct authinfo *, void *), void *); int (*auth_prefunc)(const char *, const char *, int (*)(struct authinfo *, void *), void *); void (*auth_cleanupfunc)(); int (*auth_changepwd)(const char *, /* service */ const char *, /* userid */ const char *, /* oldpassword */ const char *); /* new password */ } ;

auth_func points to a function that handles the authentication request. If succesful, auth_func is responsible for resetting the userid and groupid, changing to the authentication account`s home directory, and setting up the necessary environment variables. The first three arguments to auth_func will be SERVICE, AUTHTYPE, and AUTHDATA. The next argument is a boolean flag which is non-zero if the authentication code is being called in the context of a stand-alone authentication module, or zero if the authentication code is called directly by an application. The fifth argument points is a callback function pointer, which may be NULL. If it`s not null, auth_func should not reset the userid, groupid, or the home directory of this process, but should instead initialize the authinfo structure, which is defined as follows:

STRUCT AUTHINFO

struct authinfo { const char *sysusername; const uid_t *sysuserid; gid_t sysgroupid; const char *homedir; const char *address; /* The E-mail address */ const char *fullname; /* gecos, etc... */ const char *maildir; const char *quota; const char *passwd; const char *clearpasswd; /* For authldap */ unsigned staticindex; /* When statically-linked functions are ** called, this holds the index of the ** authentication module in authstaticlist */ } ;

The passwd, clearpasswd, and staticindex fields are not used by auth_func. Either sysusername or sysuserid must be a non-NULL pointer. sysuserid specifies an explicit userid, otherwise sysusername is looked up in the password file.

The last argument to auth_func is an opaque pointer that gets passed as the second argument to the callback function.

auth_func should return a pointer to the authenticated loginid, in dynamic memory (the memory should be free()ed after user. A NULL return indicates an authentication failure. The authentication module should set errno to EPERM in the event that it the next authentication module should have a chance to process the authentication request, or use any other errno value to immediately fail the authentication request, and rerun the original login process.

LINKED AUTHENTICATION MODULES

The auth_prefunc, auth_cleanupfunc, and auth_changepwd functions are not used by stand-alone modules, but when the authentication module is directly linked with an application.

auth_prefunc verifies that the requested userid exists. No passwords are validated, the first two arguments to auth_prefunc are the userid, and SERVICE. auth_prefunc should initialize an authinfo structure, and run the callback function, the third argument to auth_prefunc. The callback function receives the fourth argument to auth_prefunc as an opaque pointer.

auth_prefunc should come back with the callback function`s return code, if the requested userid was found. Otherwise, auth_prefunc should return a non-zero integer. A positive integer should be return in the event that this authentication request should be stopped, and a negative itneger if another authentication module can be tried. An application that links against this authentication library will run each configured authentication module`s auth_prefunc, until some module is able to process the requested userid, or until auth_prefunc comes back with a non-zero positive return code.

auth_func or auth_prefunc might allocate some internal resources, which should be freed by calling auth_cleanupfunc.

The auth_changepwd function is called to implement the change password functionality.

OTHER AUTHENTICATION LIBRARY FUNCTION

This authentication library contains several functions and macros that can be helpful in building authentication modules.

TURNING AUTH_FUNC INTO A MODULE

#define MODULE auth_func #include "mod.h"

mod.h contains template code that reads an authentication request from the previous authentication module, call auth_func, in such a manner, and appropriately run the next module in the authentication chain.

The auth.h header file also declares several useful functions that authentication-related code may find convenient.

BUILDING AUTHDAEMOND

This authentication library builds alternate versions of the authdaemond background process. Some authentication modules have dependencies on external libraries, such as authldap, authmysql, and authpgsql. The authentication library prepares separate versions of authdaemond for each authentication module with a dependency. Each one of these authdaemond versions will also include all other authentication modules that do not have dependencies.

The authentication module configuration for each authdaemond is set in the authdaemond.versions file. A new authentication module will have to be added to authdaemond.versions (potentially creating another authdaemond build). The configure script must be run after making any changes to authdaemond.versions.

FILES

/etc/courier-imap/authmodulelist - list of authentication modules read by applications that directly link with authlib

/etc/courier-imap/authdaemonrc - authdaemond configuration file

/etc/courier-imap/authldaprc - authldap configuration file

/etc/courier-imap/authmysqlrc - authmysql configuration file

/etc/courier-imap/authpgsqlrc - authpgsql configuration file

authuserdb

NAME

authlib - Courier Authentication Library

SYNOPSIS

authpam command [ arg ... ]

authpwd command [ arg ... ]

authshadow command [ arg ... ]

authuserdb command [ arg ... ]

authvchkpw command [ arg ... ]

authcram command [ arg ... ]

authmysql command [ arg ... ]

authpgsql command [ arg ... ]

authldap command [ arg ... ]

authdaemon command [ arg ... ]

authcustom command [ arg ... ]

authdaemond [ start | stop | restart ]

DESCRIPTION

This library is used for two purposes:

1. Read an E-mail address that is supposed to be for a local account. Determine the local account`s home directory, and system userid and groupid.

2. Read a login id and a password. If valid, determine the account`s home directory, system userid, and groupid.

The term "authentication" is used in the following documentation to refer to either one of these two functions. The library contains several alternative authentication implementations, that may be selected at runtime.

authdaemon: authenticates through a background daemon proxy. This is now the installation default. Unless otherwise specified, the authdaemon module will always be installed. authdaemon is installed instead of the other authentication modules. Those modules are instead compiled into a separate executable program, authdaemond that is initialized at system start, and runs in the background. The authdaemon authentication module forwards the authentication requests to authdaemond, which forwards the authentication request to the real authentication module, and the result of the request is eventually returned back to the application. Because the real authentication process runs as a persistent background process, it is possible for the authentication process to open and hold permanent connections to the back-end authentication database (be it an LDAP directory, a MySQL or a PostgreSQL server), instead of connecting and disconnecting for every request. Obviously, this tremendously improves the authentication performance.
authpam: authenticates using the system`s PAM library (pluggable authentication module). This is, essentially, a way to use existing PAM modules for authentication functionality. Note, however, that the authenticated account`s home directory, userid and groupid are still read from the /etc/passwd file, since PAM functionality is limited to validating account passwords.
authpwd: authenticates from the /etc/passwd file.
authshadow: like authpwd except passwords are read from /etc/shadow.
authuserdb: authenticates against the userdb(8) database.
authvchkpw: supports existing vpopmail/vchkpw virtual domains.
authcram: authenticates against the userdb(8) database using the challenge/response authentication mechanism (CRAM), instead of the traditional userid/password.
authmysql: authenticates against a list of mail accounts stored in an external MySQL database. The /etc/courier-imap/authmysqlrc configuration file defines the particular details regarding the MySQL database and the schema of the mail account list table.
authpgsql: authenticates against a list of mail accounts stored in an external PostgreSQL database. The authpgsqlrc configuration file defines the particular details regarding the PostgreSQL database and the schema of the mail account list table.
authldap: authenticates against a list of mail accounts stored in an external LDAP directory. The configuration file defines the particular details regarding the LDAP directory layout.
authcustom: this is a stub where custom authentication code can be added. This authentication module is just a stub that doesn`t really do anything. It`s purpose is to serve as a placeholder where custom authentication code can be easily added.

This is a complete list of available authentication modules. The actual installed authentication modules are determined by the resources on the server. For example, the authmysql authentication module will be installed only if the system provides MySQL support libraries.

AUTHDAEMON AUTHENTICATION MODULE

The following command must be executed from the system startup script in order for the authdaemon module to work (and remember that authdaemon is installed by default:

/usr/lib/courier-imap/authlib/authdaemond start

"authdaemond stop" should also be added to the system shutdown script.

The /var/lib/courier-imap/authdaemon subdirectory must be created in advance. This directory will have the filesystem socket used for interprocess communication between authdaemon and authdaemond. It goes without saying that the underlying filesystem for /var/lib/courier-imap/authdaemon must support filesystem domain sockets. This pretty much excludes all network filesystems, so this directory should reside on a local disk.

/var/lib/courier-imap/authdaemon MUST NOT HAVE any world-readable, executable or writable permissions! Under NO circumstances should this be allowed to happen. The exact permissions and ownership of /var/lib/courier-imap/authdaemon varies. For the standalone versions of Courier-IMAP and SqWebMail, /var/lib/courier-imap/authdaemon should be owned by root, and have no group or world permissions. For the Courier mail server, /var/lib/courier-imap/authdaemon should be owned by the userid that Courier is installed under, and it must be readable and writable by the Courier user and group (but no world permissions).

CONFIGURING AUTHDAEMOND

The /etc/courier-imap/authdaemonrc configuration file sets several operational parameters for the authdaemond process. See the comments in the default file installed for more information. Currently, /etc/courier-imap/authdaemonrc sets two parameters: number of daemon processes, and authentication modules/process that will be used.

Although authdaemond might include several authentication modules, not all of them may be used. This makes it possible to install the same authdaemond build on multiple systems with different authentication needs. The default module list specified in /etc/courier-imap/authdaemonrc would be a list of all the available authentication modules.

/usr/lib/courier-imap/authlib/authdaemond is actually a very short shell script that executes the real authdaemond program. The available programs are authdaemond.plain, authdaemond.ldap, authdaemond.mysql, and authdaemond.pgsql. The "plain" program contains all the authentication modules except for authldap, authmysql, and authpgsql. The "ldap" program includes all the authentication modules in "plain", plus authldap Ditto for the "mysql" and "pgsql" processes.

This arrangement allows convenient creation of pre-configured binary packages. The authdaemond shell script runs authdaemond.plain only if none of the other processes are installed on the system. First, it checks if authdaemond.ldap, authdaemond.mysql, or authdaemond.pgsql is installed. If not, authdaemond.plain is brought up. This makes it possible to prepare a basic binary package that provides only basic authentication services and does not require either LDAP, MySQL, or PostgreSQL runtime support on the server. If either of these authentication requirements are needed, a separate binary sub-package will load the appropriate authdaemond process.

Note that it is not possible to use both LDAP and MySQL, for example, authentication at the same time. That`s because their support is in different authdaemond processes, and only one authdaemond process can run at the same time. If both (or all three non-plain processes) are installed, the authdaemond script picks either the first one it finds, or whatever is explicitly specified in the /etc/courier-imap/authdaemonrc configuration file.

The number of authdaemond processes is also set in this configuration file. The more processes that are started, the more authentication requests can be handled. If authdaemon does not receive an answer within a moderate amount of time, it will declare an authentication failure, and abort. Try increasing the number of processes if you start seeing random authentication failures. However, that should only be used as a stop-gap measure. If the default number of authdaemond processes proves to be insufficient, it is far more likely that more resources are needed for the server: more RAM, a faster disk, or a faster CPU, at least in the humble opinion of the author. Increasing the number of processes should only be used as a stop-gap measure, until a more thorough analysis on the bottleneck can be made.

/usr/lib/courier-imap/authlib/authdaemond restart

Run the above command after making any changes to /etc/courier-imap/authdaemonrc. "authdaemond restart" is required for any changes to take effect.

AUTHENTICATION PROTOCOL

The rest of this documentation describes the internal protocol used by this authentication library. It is only of interest to developers who wish to extend the authentication library to support a custom authentication module, or a derived extension to an existing module.

The original implementation of this authentication library used small, self-contained, binary programs, named for their authentication module: authldap, authpam, and others. Later, the authdaemon module came about, which wrapped the other authentication modules into a separate background daemon process, which communicated with the authdaemon module. The authdaemon module is now always enabled by default, but it is still possible to build and install each authentication module as a self-contained binary program. Note, however, that applications such as SqWebMail, and Courier link directly with all the authentication modules, and will not use external modules for authentication.

authdaemon came about as a direct result of technical issues that prevented SqWebMail and Courier from using external binary modules. authdaemond is really nothing more than a simple application that links directly with the authentication modules, and talks to the authdaemon authentication module that follows this authentication protocol.

STAND-ALONE AUTHENTICATION MODULES

This section describes the authentication protocol for self-contained authentication modules. Although the default configuration no longer uses self-contained modules, the stand-alone protocol serves as a foundation for the protocol used by authentication modules as part of the authdaemond authentication process, or when they are linked directly with the application that uses this authentication library.

Here`s the typical way that stand-alone authentication modules are used:

1. A list of authentication modules are read from a configuration file. Multiple authentication modules could be available, but not all of them are required in most situations.

2. The application executes the following command:

LOGIN AUTHMODULE1 AUTHMODULE2 ... APP

LOGIN is a full pathname to an application that reads the authentication information, such as the userid and a password. Arguments to LOGIN are full pathnames to each authentication module (if there are more than one), followed by a full pathname to the main application.

3. LOGIN reads the userid and password, then runs the program specified by its first argument, which is the first authentication module. The remaining arguments are passed to the new process. The mechanism by which the authentication information is passed to the authentication module is described later.

4. Each authentication module reads the authentication information, and determines if the previous authentication module succesfully processed the authentication request. If not, the module attempts to authenticate it itself. In any event, the module runs the next program specified by its first argument, and the remaining arguments are passed along to the next program. If any previous authentication module succesfully processed the authentication request, the next program is run immediately without any further processing.

5. Eventually, APP runs, APP reads the authentication information and determines whether any authentication module managed to succesfully process the authentication request. If so, APP runs normally. Otherwise, APP runs LOGIN with its original arguments in order to return an error message ("Password invalid", or something similar) and read the next authentication request.

Daisy-chaining authentication modules, in this fashion, makes it possible to have hybrid systems that use multiple authentication modules. Example: using authpam to authenticate system accounts, and authmysql to authentication virtual mailboxes without a corresponding system account.

Here`s a more detailed description of the overall process:

THE LOGIN PROCESS

The LOGIN process checks if the AUTHARGC environment variable is set. If not, this is the first time the LOGIN process comes up, and LOGIN displays the initial login prompt. Additionally, the command line arguments to LOGIN are literal copied to the AUTHARGC and AUTHARGVn environment variables. That is: the number of command line arguments is saved in AUTHARGC; the zeroth command line argument is saved in AUTHARGV0; the remaining command line arguments are saved in AUTHARGV1, AUTHARGV2, and so on.

After obtaining the authentication information (such as the userid and password), LOGIN creates a pipe, and arranges for the output end of the pipe to be located on file descriptor #3. The LOGIN process forks; the original process then executes the first authentication module, in the manner described earlier; the child process writes the authentication record to the pipe, then terminates.

The authentication record is a chunk of data in the following format:

: SERVICE<NEWLINE>AUTHTYPE<NEWLINE>AUTHDATA

Each occurence of <NEWLINE> represents an ASCII linefeed character (#10). "SERVICE" identifies the service that originates the authentication request, such as "imap", or "webmail". Authentication module may use this identifier, or ignore it.

"AUTHTYPE" identifies the format of the authentication request. Everything after the second <NEWLINE> is an opaque blob of data, whose format is determined by AUTHTYPE.

: Note: There`s a theoretical upper limit on the maximum size of the authentication record. It is high enough not to matter in most situations (the total number of characters allowed cannot be more than 8189 characters on a typical GNU/Linux system).

The following AUTHTYPE formats are currently defined:

login: A typical userid/password authentication request. AUTHDATA contains the following data: userid<NEWLINE>password<NEWLINE>.
cram-md5: Specifies the CRAM-MD5 authentication request. AUTHDATA contains the following data: challenge<NEWLINE>response<NEWLINE>. The "challenge" and "response" strings are base64-encoded.
cram-sha1: Specifies the CRAM-SHA1 authentication request, instead of CRAM-MD5, and uses the same format for AUTHDATA.

THE AUTHENTICATION MODULE

The first thing an authentication module does is check if the environment variable AUTHENTICATED is set to a non-empty string. If so, it means that a previous authentication module has handled the authentication request, so this module simply runs the next program, specified by the first argument to this authentication module.

Otherwise, the authentication module reads the authentication record from file descriptor #3, and determines whether it wants to try this authentication record. If not, the module creates a new pipe, arranges the output of the pipe to be on file descriptor #3, forks, the parent process runs the next authentication module, and the child process writes the authentication record to the pipe, then exits.

There are two ways to handle an authentication request: 1) Use the AUTHARGC and AUTHARGVn variables to restart the entire authentication process - this is used in the event it is determined that the authentication request must be failed, or 2) run the next daisy-changed module, in the manner described previously, when it is determined that another authentication module can attempt to try to handle this request.

The following action occurs when the authentication module succesfully validates an authentication request:

1. The authenticated login ID is saved in the AUTHENTICATED environment variable.

2. The process`s userid and groupid are reset to the corresponding userid and groupid of the authenticated login id, and the current directory is set to the process`s defined home directory.

3. Some additional environment variables may also be initialized: AUTHFULLNAME - the login ID`s full name; MAILDIR - the login ID`s default maildir mailbox; MAILDIRQUOTA - the requested maildir quota.

THE APPLICATION PROCESS

Eventually, APP runs. The process closes file descriptor #3 (if it`s open, and ignores the error if file descriptor #3 does not exist). If the AUTHENTICATED environment variable is set, it must mean that an authentication module was able to handle this authentication request, so APP starts up and runs normally. Otherwise the original command is reconstructed from the AUTHARGC and AUTHARGVn variables, and the initial login process runs again.

LIBRARY FUNCTIONS

This authentication library provides several convenient functions which can be used to quickly create a compliant login process, and its corresponding application. The login process should be structured as follows:

A SAMPLE LOGIN PROCESS

int main(int argc, char **argv) { if (authmoduser(argc, argv, TIMEOUT, ERR_TIMEOUT)) { /* Print initial greeting here */ } else { /* Error: invalid userid/password */ } /* read userid and password */ authmod(argc-1, argv+1, SERVICE, AUTHTYPE, AUTHDATA); }

The authmoduser function takes care of copying the command line parameters to their corresponding environment variables, and checking whether or not this is the initial time this process runs, or if it is running again after a failed authentication process. TIMEOUT specifies the absolute login timeout, authmoduser quietly terminates the process if it runs due to a failed authentication request and at least TIMEOUT seconds have elapsed since the first time authmoduser was run. ERR_TIMEOUT specifies the number of seconds that authmoduser will sleep after a failed authentication request.

The SERVICE, AUTHTYPE, and AUTHDATA arguments to authmod are null-terminated character strings that form the authentication request. authmod takes care of setting up the pipe to the first authentication module, and runs it.

The application process is even simpler:

A SAMPLE APP PROCESS

int main(int argc, char **argv) { const char *loginid=authmodclient(); /* Application begins normally */ }

The authmodclient function returns the authenticated login ID. If the authentication request failed, authmodclient reruns the original login process, and doesn`t return.

INSIDE AN AUTHENTICATION MODULES

An authentication module needs to define the following structure:

STRUCT AUTHSTATICINFO

struct authstaticinfo { const char *auth_name; char * (*auth_func)(const char *, const char *, char *, int, void (*)(struct authinfo *, void *), void *); int (*auth_prefunc)(const char *, const char *, int (*)(struct authinfo *, void *), void *); void (*auth_cleanupfunc)(); int (*auth_changepwd)(const char *, /* service */ const char *, /* userid */ const char *, /* oldpassword */ const char *); /* new password */ } ;

auth_func points to a function that handles the authentication request. If succesful, auth_func is responsible for resetting the userid and groupid, changing to the authentication account`s home directory, and setting up the necessary environment variables. The first three arguments to auth_func will be SERVICE, AUTHTYPE, and AUTHDATA. The next argument is a boolean flag which is non-zero if the authentication code is being called in the context of a stand-alone authentication module, or zero if the authentication code is called directly by an application. The fifth argument points is a callback function pointer, which may be NULL. If it`s not null, auth_func should not reset the userid, groupid, or the home directory of this process, but should instead initialize the authinfo structure, which is defined as follows:

STRUCT AUTHINFO

struct authinfo { const char *sysusername; const uid_t *sysuserid; gid_t sysgroupid; const char *homedir; const char *address; /* The E-mail address */ const char *fullname; /* gecos, etc... */ const char *maildir; const char *quota; const char *passwd; const char *clearpasswd; /* For authldap */ unsigned staticindex; /* When statically-linked functions are ** called, this holds the index of the ** authentication module in authstaticlist */ } ;

The passwd, clearpasswd, and staticindex fields are not used by auth_func. Either sysusername or sysuserid must be a non-NULL pointer. sysuserid specifies an explicit userid, otherwise sysusername is looked up in the password file.

The last argument to auth_func is an opaque pointer that gets passed as the second argument to the callback function.

auth_func should return a pointer to the authenticated loginid, in dynamic memory (the memory should be free()ed after user. A NULL return indicates an authentication failure. The authentication module should set errno to EPERM in the event that it the next authentication module should have a chance to process the authentication request, or use any other errno value to immediately fail the authentication request, and rerun the original login process.

LINKED AUTHENTICATION MODULES

The auth_prefunc, auth_cleanupfunc, and auth_changepwd functions are not used by stand-alone modules, but when the authentication module is directly linked with an application.

auth_prefunc verifies that the requested userid exists. No passwords are validated, the first two arguments to auth_prefunc are the userid, and SERVICE. auth_prefunc should initialize an authinfo structure, and run the callback function, the third argument to auth_prefunc. The callback function receives the fourth argument to auth_prefunc as an opaque pointer.

auth_prefunc should come back with the callback function`s return code, if the requested userid was found. Otherwise, auth_prefunc should return a non-zero integer. A positive integer should be return in the event that this authentication request should be stopped, and a negative itneger if another authentication module can be tried. An application that links against this authentication library will run each configured authentication module`s auth_prefunc, until some module is able to process the requested userid, or until auth_prefunc comes back with a non-zero positive return code.

auth_func or auth_prefunc might allocate some internal resources, which should be freed by calling auth_cleanupfunc.

The auth_changepwd function is called to implement the change password functionality.

OTHER AUTHENTICATION LIBRARY FUNCTION

This authentication library contains several functions and macros that can be helpful in building authentication modules.

TURNING AUTH_FUNC INTO A MODULE

#define MODULE auth_func #include "mod.h"

mod.h contains template code that reads an authentication request from the previous authentication module, call auth_func, in such a manner, and appropriately run the next module in the authentication chain.

The auth.h header file also declares several useful functions that authentication-related code may find convenient.

BUILDING AUTHDAEMOND

This authentication library builds alternate versions of the authdaemond background process. Some authentication modules have dependencies on external libraries, such as authldap, authmysql, and authpgsql. The authentication library prepares separate versions of authdaemond for each authentication module with a dependency. Each one of these authdaemond versions will also include all other authentication modules that do not have dependencies.

The authentication module configuration for each authdaemond is set in the authdaemond.versions file. A new authentication module will have to be added to authdaemond.versions (potentially creating another authdaemond build). The configure script must be run after making any changes to authdaemond.versions.

FILES

/etc/courier-imap/authmodulelist - list of authentication modules read by applications that directly link with authlib

/etc/courier-imap/authdaemonrc - authdaemond configuration file

/etc/courier-imap/authldaprc - authldap configuration file

/etc/courier-imap/authmysqlrc - authmysql configuration file

/etc/courier-imap/authpgsqlrc - authpgsql configuration file

backend-spec

NAME

backend-spec - interface between jw and its backends

DESCRIPTION

jw(1) calls backends like backends/html to do the "real" conversion work. The backend gets all necessary data delivered via environment variables ready to use.

This documentation describes those environment variables.

The backend is run in the directory where the output files are to be created. It should return 0 if there weren`t any problem, and return a positive value otherwise.

VARIABLES

SGML_FILE_NAME: The bare name of the source file

SGML_FILE: The full name and path of the source file

SGML_JADE: The name of the parser (usually Jade or OpenJade)

SGML_ARGUMENTS: The full argument-string for Jade or OpenJade

SGML_CATALOG_FILES: The list of catalog files needed by Jade or OpenJade

SGML_STYLESHEET: The style sheet to use

SGML_BASE_DIR: The base directory of the SGML system (default is /usr/share/sgml)

FILES

AUTHORS

Jochem Huhmann <joh@revier.com>

boot

NAME

boot-scripts - General description of boot sequence

DESCRIPTION

The boot sequence varies in details among systems but can be roughly divided to the following steps: (i) hardware boot, (ii) OS loader, (iii) kernel startup, (iv) init and inittab, (v) boot scripts. We will describe each of these in more detail below.

Hardware-boot

After power-on or hard reset, control is given to a program stored on read only memory (normally PROM). In PC we usually call this program the BIOS.

This program normally makes a basic self-test of the machine and accesses non-volatile memory to read further parameters. This memory in the PC is battery-backed CMOS memory, so most people refer to it as the CMOS, although outside of the PC world, it is usually called nvram (non-volatile ram).

The parameters stored in the nvram vary between systems, but as a minimum, the hardware boot program should know what is the boot device, or which devices to probe as possible boot devices.

Then the hardware boot stage accesses the boot device, loads the OS Loader, which is located on a fixed position on the boot device, and transfers control to it.

Note:: We do not cover here booting from network. Those who want to investigate this subject may want to research: DHCP, TFTP, PXE, Etherboot.

OS Loader

In PC, the OS Loader is located in the first sector of the boot device - this is the MBR (Master Boot Record).

In most systems, this primary loader is very limited due to various constraints. Even on non-PC systems there are some limitations to the size and complexity of this loader, but the size limitation of the PC MBR (512 bytes including the partition table) makes it almost impossible to squeeze a full OS Loader into it.

Therefore, most operating systems make the primary loader call a secondary OS loader which may be located on a specified disk partition.

In Linux the OS loader is normally lilo(8) or grub(8). Both of them may install either as secondary loaders (where the DOS installed MBR points to them), or as a two part loader where they provide special MBR containing the bootstrap code to load the second part of the loader from the root partition.

The main job of the OS Loader is to locate the kernel on the disk, load it and run it. Most OS loaders allow interactive use, to enable specification of alternative kernel (maybe a backup in case the last compiled one isn`t functioning) and to pass optional parameters to the kernel.

Kernel Startup

When the kernel is loaded, it initializes the devices (via their drivers), starts the swapper (it is a "kernel process", called kswapd in modern Linux kernels), and mounts the root file system (/).

Some of the parameters that may be passed to the kernel relate to these activities (e.g: You can override the default root file system). For further information on Linux kernel parameters read bootparam(7).

Only then the kernel creates the first (user land) process which is numbered 1. This process executes the program /sbin/init, passing any parameters that weren`t handled by the kernel already.

init and inittab

When init starts it reads /etc/inittab for further instructions. This file defines what should be run in different run-levels.

This gives the system administrator an easy management scheme, where each run-level is associated with a set of services (e.g: S is single-user, on 2 most network services start, etc.). The administrator may change the current run-level via init(8) and query the current run-level via runlevel(8).

However, since it is not convenient to manage individual services by editing this file, inittab only bootstraps a set of scripts that actually start/stop the individual services.

Boot Scripts

Note:: The following description applies to SYSV-R4 based system, which currently covers most commercial Unices (Solaris, HPUX, Irix, Tru64) as well as the major Linux distributions (RedHat, Debian, Mandrake, Suse, Caldera). Some systems (Slackware Linux, FreeBSD, OpenBSD) have a somewhat different scheme of boot scripts.

For each managed service (mail, nfs server, cron, etc.) there is a single startup script located in a specific directory (/etc/init.d in most versions of Linux). Each of these scripts accepts as a single argument the word `start` -- causing it to start the service, or the word accept other "convenience" parameters (e.g: `restart`, to stop and then start, `status` do display the service status). Running the script without parameters displays the possible arguments.

Sequencing Directories

To make specific scripts start/stop at specific run-levels and in specific order, there are sequencing directories. These are normally in /etc/rc[0-6S].d. In each of these directories there are links (usually symbolic) to the scripts in the init.d directory.

A primary script (usually /etc/rc) is called from inittab(5) and calls the services scripts via the links in the sequencing directories. All links with names that begin with `S` are being called with the argument `start` (thereby starting the service). All links with names that begin with `K` are being called with the argument `stop` (thereby stopping the service).

To define the starting or stopping order within the same run-level, the names of the links contain order-numbers. Also, to make the names clearer, they usually end with the name of the service they refer to. Example: the link /etc/rc2.d/S80sendmail starts the sendmail service on runlevel 2. This happens after /etc/rc2.d/S12syslog is run but before /etc/rc2.d/S90xfs is run.

To manage the boot order and run-levels, we have to manage these links. However, on many versions of Linux, there are tools to help with this task (e.g: chkconfig(8)).

Boot Configuration

Usually the daemons started may optionally receive command line options and parameters. To allow system administrators to change these parameters without editing the boot scripts themselves, configuration files are used. These are located in a specific directory (/etc/sysconfig on RedHat systems) and are used by the boot scripts.

In older Unices, these files contained the actual command line options for the daemons, but in modern Linux systems (and also in HPUX), these files just contain shell variables. The boot scripts in /etc/init.d source the configuration files, and then use the variable values.

FILES

/etc/init.d/, /etc/rc[S0-6].d/. /etc/sysconfig/

capabilities

NAME

capabilities - overview of Linux capabilities

DESCRIPTION

For the purpose of performing permission checks, traditional Unix implementations distinguish two categories of processes: privileged processes (whose effective user ID is 0, referred to as superuser or root), and unprivileged processes (whose effective UID is non-zero). Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process`s credentials (usually: effective UID, effective GID, and supplementary group list).

Starting with kernel 2.2, Linux provides an (as yet incomplete) system of capabilities, which divide the privileges traditionally associated with superuser into distinct units that can be independently enabled and disabled.

Capabilities List

As at Linux 2.4.20, the following capabilities are implemented:

CAP_CHOWN: Allow arbitrary changes to file UIDs and GIDs (see chown(2)).
CAP_DAC_OVERRIDE: Bypass file read, write, and execute permission checks. (DAC = "discretionary access control".)
CAP_DAC_READ_SEARCH: Bypass file read permission checks and directory read and execute permission checks.
CAP_FOWNER: Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file (e.g., utime(2)), excluding those operations covered by the CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH; ignore sticky bit on file deletion.
CAP_FSETID: Don`t clear set-user-ID and set-group-ID bits when a file is modified; permit setting of the set-group-ID bit for a file whose GID does not match the file system or any of the supplementary GIDs of the calling process.
CAP_IPC_LOCK: Permit memory locking (mlock(2), mlockall(2), shmctl(2)).
CAP_IPC_OWNER: Bypass permission checks for operations on System V IPC objects.
CAP_KILL: Bypass permission checks for sending signals (see kill(2)).
CAP_LEASE: (Linux 2.4 onwards) Allow file leases to be established on arbitrary files (see fcntl(2)).
CAP_LINUX_IMMUTABLE: Allow setting of the EXT2_APPEND_FL and EXT2_IMMUTABLE_FL ext2 extended file attributes.
CAP_MKNOD: (Linux 2.4 onwards) Allow creation of special files using mknod(2).
CAP_NET_ADMIN: Allow various network-related operations (e.g., setting privileged socket options, enabling multicasting, interface configuration, modifying routing tables).
CAP_NET_BIND_SERVICE: Allow binding to Internet domain reserved socket ports (port numbers less than 1024).
CAP_NET_BROADCAST: (Unused) Allow socket broadcasting, and listening multicasts.
CAP_NET_RAW: Permit use of RAW and PACKET sockets.
CAP_SETGID: Allow arbitrary manipulations of process GIDs and supplementary GID list; allow forged GID when passing socket credentials via Unix domain sockets.
CAP_SETPCAP: Grant or remove any capability in the caller`s permitted capability set to or from any other process.
CAP_SETUID: Allow arbitrary manipulations of process UIDs (setuid(2), etc.); allow forged UID when passing socket credentials via Unix domain sockets.
CAP_SYS_ADMIN: Permit a range of system administration operations including: quotactl(2), mount(2), swapon(2), sethostname(2), setdomainname(2), IPC_SET and IPC_RMID operations on arbitrary System V IPC objects; allow forged UID when passing socket credentials.
CAP_SYS_BOOT: Permit calls to reboot(2).
CAP_SYS_CHROOT: Permit calls to chroot(2).
CAP_SYS_MODULE: Allow loading and unloading of kernel modules; allow modifications to capability bounding set.
CAP_SYS_NICE: Allow raising process nice value (nice(2), setpriority(2)) and changing of the nice value for arbitrary processes; allow setting of real-time scheduling policies for calling process, and setting scheduling policies and priorities for arbitrary processes (sched_setscheduler(2), sched_setparam(2)).
CAP_SYS_PACCT: Permit calls to acct(2).
CAP_SYS_PTRACE: Allow arbitrary processes to be traced using ptrace(2)
CAP_SYS_RAWIO: Permit I/O port operations (iopl(2) and ioperm(2)).
CAP_SYS_RESOURCE: Permit: use of reserved space on ext2 file systems; ioctl(2) calls controlling ext3 journaling; disk quota limits to be overridden; resource limits to be increased (see setrlimit(2)); RLIMIT_NPROC resource limit to be overridden; msg_qbytes limit for a message queue to be raised above the limit in /proc/sys/kernel/msgmnb (see msgop(2) and msgctl(2).
CAP_SYS_TIME: Allow modification of system clock (settimeofday(2), adjtimex(2)); allow modification of real-time (hardware) clock
CAP_SYS_TTY_CONFIG: Permit calls to vhangup(2).

Process Capabilities

Each process has three capability sets containing zero or more of the above capabilities:

Effective:: the capabilities used by the kernel to perform permission checks for the process.
Permitted:: the capabilities that the process may assume (i.e., a limiting superset for the the effective and inheritable sets). If a process drops a capability from its permitted set, it can never re-acquire that capability (unless it execs a set-UID-root program).
Inherited:: the capabilities preserved across an execve(2).

In the current implementation, a process is granted all permitted and effective capabilities (subject to the operation of the capability bounding set described below) when it execs a set-UID-root program, or if a process with a real UID of zero execs a new program.

A child created via fork(2) inherits copies of its parent`s capability sets.

Using capset(2), a process may manipulate its own capability sets, or, if it has the CAP_SETPCAP capability, those of another process.

Capability bounding set

When a program is execed, the permitted and effective capabities are ANDed with the current value of the so-called capability bounding set, defined in the file /proc/sys/kernel/cap-bound. This parameter can be used to place a system-wide limit on the capabilities granted to all subsequently executed programs. (Confusingly, this bit mask parameter is expressed as a signed decimal number in /proc/sys/kernel/cap-bound.)

Only the init process may set bits in the capability bounding set; other than that, the superuser may only clear bits in this set.

On a standard system the capability bounding set always masks out the CAP_SETPCAP capability. To remove this restriction, modify the definition of CAP_INIT_EFF_SET in include/linux/capability.h and rebuild the kernel.

Current and Future Implementation

A full implementation of capabilities requires:

1.: that for all privileged operations, the kernel check whether the process has the required capability in its effective set.
2.: that the kernel provide system calls allowing a process`s capability sets to be changed and retrieved.
3.: file system support for attaching capabilities to an executable file, so that a process gains those capabilities when the file is execed.

As at Linux 2.4.20, only the first two of these requirements are met.

Eventually, it should be possible to associate three capability sets with an executable file, which, in conjunction with the capability sets of the process, will determine the capabilities of a process after an exec:

Allowed:: this set is ANDed with the process`s inherited set to determine which inherited capabilities are permitted to the process after the exec.
Forced:: the capabilities automatically permitted to the process, regardless of the process`s inherited capabilities.
Effective:: those capabilities in the process`s new permitted set are also to be set in the new effective set. (F(effective) would normally be either all zeroes or all ones.)

In the meantime, since the current implementation does not support file capability sets, during an exec:

1.: All three file capability sets are initially assumed to be cleared.
2.: If a set-UID-root program is being execed, or the real user ID of the process is 0 (root) then the file allowed and forced sets are defined to be all ones (i.e., all capabilities set).
3.: If a set-UID-root program is being executed, then the file effective set is defined to be all ones.

During an exec, the kernel calculates the new capabilities of the process using the following algorithm:

P`(permitted) = (P(inherited) & F(allowed)) | (F(forced) & cap_bset) P`(effective) = P`(permitted) & F(effective) P`(inherited) = P(inherited) [i.e., unchanged]

where:

P: denotes the value of a process capability set before the exec
P`: denotes the value of a capability set after the exec
F: denotes a file capability set
cap_bset: is the value of the capability bounding set.

NOTES

The libcap package provides a suite of routines for setting and getting process capabilities that is more comfortable and less likely to change than the interface provided by capset(2) and capget(2).

CONFORMING TO

No standards govern capabilities, but the Linux capability implementation is based on the withdrawn POSIX 1003.1e draft standard.

BUGS

There is as yet no file system support allowing capabilities to be associated with executable files.

checkpoint

NAME

CHECKPOINT - force a transaction log checkpoint

SYNOPSIS

CHECKPOINT

DESCRIPTION

Write-Ahead Logging (WAL) puts a checkpoint in the transaction log every so often. (To adjust the automatic checkpoint interval, see the run-time configuration options checkpoint_segments and checkpoint_timeout.) The CHECKPOINT command forces an immediate checkpoint when the command is issued, without waiting for a scheduled checkpoint.

A checkpoint is a point in the transaction log sequence at which all data files have been updated to reflect the information in the log. All data files will be flushed to disk. Refer to the the chapter called ``Write-Ahead Logging`` in the documentation for more information about the WAL system.

Only superusers may call CHECKPOINT. The command is not intended for use during normal operation.

COMPATIBILITY

The CHECKPOINT command is a PostgreSQL language extension.

cluster

NAME

CLUSTER - cluster a table according to an index

SYNOPSIS

CLUSTER indexname ON tablename CLUSTER tablename CLUSTER

DESCRIPTION

CLUSTER instructs PostgreSQL to cluster the table specified by tablename based on the index specified by indexname. The index must already have been defined on tablename.

When a table is clustered, it is physically reordered based on the index information. Clustering is a one-time operation: when the table is subsequently updated, the changes are not clustered. That is, no attempt is made to store new or updated rows according to their index order. If one wishes, one can periodically recluster by issuing the command again.

When a table is clustered, PostgreSQL remembers on which index it was clustered. The form CLUSTER tablename, reclusters the table on the same index that it was clustered before.

CLUSTER without any parameter reclusters all the tables in the current database that the calling user owns, or all tables if called by a superuser. (Never-clustered tables are not included.) This form of CLUSTER cannot be called from inside a transaction or function.

When a table is being clustered, an ACCESS EXCLUSIVE lock is acquired on it. This prevents any other database operations (both reads and writes) from operating on the table until the CLUSTER is finished.

PARAMETERS

indexname: The name of an index.
tablename: The name (possibly schema-qualified) of a table.

NOTES

In cases where you are accessing single rows randomly within a table, the actual order of the data in the table is unimportant. However, if you tend to access some data more than others, and there is an index that groups them together, you will benefit from using CLUSTER. If you are requesting a range of indexed values from a table, or a single indexed value that has multiple rows that match, CLUSTER will help because once the index identifies the heap page for the first row that matches, all other rows that match are probably already on the same heap page, and so you save disk accesses and speed up the query.

During the cluster operation, a temporary copy of the table is created that contains the table data in the index order. Temporary copies of each index on the table are created as well. Therefore, you need free space on disk at least equal to the sum of the table size and the index sizes.

Because CLUSTER remembers the clustering information, one can cluster the tables one wants clustered manually the first time, and setup a timed event similar to VACUUM so that the tables are periodically reclustered.

Because the planner records statistics about the ordering of tables, it is advisable to run ANALYZE on the newly clustered table. Otherwise, the planner may make poor choices of query plans.

There is another way to cluster data. The CLUSTER command reorders the original table using the ordering of the index you specify. This can be slow on large tables because the rows are fetched from the heap in index order, and if the heap table is unordered, the entries are on random pages, so there is one disk page retrieved for every row moved. (PostgreSQL has a cache, but the majority of a big table will not fit in the cache.) The other way to cluster a table is to use

CREATE TABLE newtable AS SELECT columnlist FROM table ORDER BY columnlist;

which uses the PostgreSQL sorting code in the ORDER BY clause to create the desired order; this is usually much faster than an index scan for unordered data. You then drop the old table, use ALTER TABLE ... RENAME to rename newtable to the old name, and recreate the table`s indexes. However, this approach does not preserve OIDs, constraints, foreign key relationships, granted privileges, and other ancillary properties of the table --- all such items must be manually recreated.

EXAMPLES

Cluster the table employees on the basis of its index emp_ind:

CLUSTER emp_ind ON emp;

Cluster the employees relation using the same index that was used before:

CLUSTER emp;

Cluster all the tables on the database that have previously been clustered:

CLUSTER;

COMPATIBILITY

There is no CLUSTER statement in the SQL standard.

commit

NAME

COMMIT - commit the current transaction

SYNOPSIS

COMMIT [ WORK | TRANSACTION ]

DESCRIPTION

COMMIT commits the current transaction. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs.

PARAMETERS

WORK
TRANSACTION: Optional key words. They have no effect.

NOTES

Use ROLLBACK [rollback(7)] to abort a transaction.

Issuing COMMIT when not inside a transaction does no harm, but it will provoke a warning message.

EXAMPLES

To commit the current transaction and make all changes permanent:

COMMIT;

COMPATIBILITY

The SQL standard only specifies the two forms COMMIT and COMMIT WORK. Otherwise, this command is fully conforming.

create_aggregate

NAME

CREATE AGGREGATE - define a new aggregate function

SYNOPSIS

CREATE AGGREGATE name ( BASETYPE = input_data_type, SFUNC = sfunc, STYPE = state_data_type [ , FINALFUNC = ffunc ] [ , INITCOND = initial_condition ] )

DESCRIPTION

CREATE AGGREGATE defines a new aggregate function. Some aggregate functions for base types such as min(integer) and avg(double precision) are already provided in the standard distribution. If one defines new types or needs an aggregate function not already provided, then CREATE AGGREGATE can be used to provide the desired features.

If a schema name is given (for example, CREATE AGGREGATE myschema.myagg ...) then the aggregate function is created in the specified schema. Otherwise it is created in the current schema.

An aggregate function is identified by its name and input data type. Two aggregates in the same schema can have the same name if they operate on different input types. The name and input data type of an aggregate must also be distinct from the name and input data type(s) of every ordinary function in the same schema.

An aggregate function is made from one or two ordinary functions: a state transition function sfunc, and an optional final calculation function ffunc. These are used as follows:

sfunc( internal-state, next-data-item ) ---> next-internal-state ffunc( internal-state ) ---> aggregate-value

PostgreSQL creates a temporary variable of data type stype to hold the current internal state of the aggregate. At each input data item, the state transition function is invoked to calculate a new internal state value. After all the data has been processed, the final function is invoked once to calculate the aggregate`s return value. If there is no final function then the ending state value is returned as-is.

An aggregate function may provide an initial condition, that is, an initial value for the internal state value. This is specified and stored in the database as a column of type text, but it must be a valid external representation of a constant of the state value data type. If it is not supplied then the state value starts out null.

If the state transition function is declared ``strict``, then it cannot be called with null inputs. With such a transition function, aggregate execution behaves as follows. Null input values are ignored (the function is not called and the previous state value is retained). If the initial state value is null, then the first nonnull input value replaces the state value, and the transition function is invoked beginning with the second nonnull input value. This is handy for implementing aggregates like max. Note that this behavior is only available when state_data_type is the same as input_data_type. When these types are different, you must supply a nonnull initial condition or use a nonstrict transition function.

If the state transition function is not strict, then it will be called unconditionally at each input value, and must deal with null inputs and null transition values for itself. This allows the aggregate author to have full control over the aggregate`s handling of null values.

If the final function is declared ``strict``, then it will not be called when the ending state value is null; instead a null result will be returned automatically. (Of course this is just the normal behavior of strict functions.) In any case the final function has the option of returning a null value. For example, the final function for avg returns null when it sees there were zero input rows.

PARAMETERS

name: The name (optionally schema-qualified) of the aggregate function to create.
input_data_type: The input data type on which this aggregate function operates. This can be specified as "ANY" for an aggregate that does not examine its input values (an example is count(*)).
sfunc: The name of the state transition function to be called for each input data value. This is normally a function of two arguments, the first being of type state_data_type and the second of type input_data_type. Alternatively, for an aggregate that does not examine its input values, the function takes just one argument of type state_data_type. In either case the function must return a value of type state_data_type. This function takes the current state value and the current input data item, and returns the next state value.
state_data_type: The data type for the aggregate`s state value.
ffunc: The name of the final function called to compute the aggregate`s result after all input data has been traversed. The function must take a single argument of type state_data_type. The return data type of the aggregate is defined as the return type of this function. If ffunc is not specified, then the ending state value is used as the aggregate`s result, and the return type is state_data_type.
initial_condition: The initial setting for the state value. This must be a string constant in the form accepted for the data type state_data_type. If not specified, the state value starts out null.

The parameters of CREATE AGGREGATE can be written in any order, not just the order illustrated above.

EXAMPLES

See the section called ``User-defined Aggregates`` in the documentation.

COMPATIBILITY

CREATE AGGREGATE is a PostgreSQL language extension. The SQL standard does not provide for user-defined aggregate function.

create_conversion

NAME

CREATE CONVERSION - define a new conversion

SYNOPSIS

CREATE [DEFAULT] CONVERSION name FOR source_encoding TO dest_encoding FROM funcname

DESCRIPTION

CREATE CONVERSION defines a new encoding conversion. Conversion names may be used in the convert function to specify a particular encoding conversion. Also, conversions that are marked DEFAULT can be used for automatic encoding conversion between client and server. For this purpose, two conversions, from encoding A to B and from encoding B to A, must be defined.

To be able to create a conversion, you must have EXECUTE privilege on the function and CREATE privilege on the destination schema.

PARAMETERS

DEFAULT

The DEFAULT clause indicates that this conversion is the default for this particular source to destination encoding. There should be only one default encoding in a schema for the encoding pair.

name

The name of the conversion. The conversion name may be schema-qualified. If it is not, the conversion is defined in the current schema. The conversion name must be unique within a schema.

source_encoding

The source encoding name.

dest_encoding

The destination encoding name.

funcname

The function used to perform the conversion. The function name may be schema-qualified. If it is not, the function will be looked up in the path.

The function must have the following signature:

conv_proc( integer, -- source encoding ID integer, -- destination encoding ID cstring, -- source string (null terminated C string) cstring, -- destination string (null terminated C string) integer -- source string length ) RETURNS void;

NOTES

Use DROP CONVERSION to remove user-defined conversions.

The privileges required to create a conversion may be changed in a future release.

EXAMPLES

To create a conversion from encoding UNICODE to LATIN1 using myfunc:

CREATE CONVERSION myconv FOR `UNICODE` TO `LATIN1` FROM myfunc;

COMPATIBILITY

CREATE CONVERSION is a PostgreSQL extension. There is no CREATE CONVERSION statement in the SQL standard.

create_domain

NAME

CREATE DOMAIN - define a new domain

SYNOPSIS

CREATE DOMAIN name [AS] data_type [ DEFAULT expression ] [ constraint [ ... ] ] where constraint is: [ CONSTRAINT constraint_name ] { NOT NULL | NULL | CHECK (expression) }

DESCRIPTION

CREATE DOMAIN creates a new data domain. The user who defines a domain becomes its owner.

If a schema name is given (for example, CREATE DOMAIN myschema.mydomain ...) then the domain is created in the specified schema. Otherwise it is created in the current schema. The domain name must be unique among the types and domains existing in its schema.

Domains are useful for abstracting common fields between tables into a single location for maintenance. For example, an email address column may be used in several tables, all with the same properties. Define a domain and use that rather than setting up each table`s constraints individually.

PARAMETERS

name: The name (optionally schema-qualified) of a domain to be created.
data_type: The underlying data type of the domain. This may include array specifiers.
DEFAULT expression: The DEFAULT clause specifies a default value for columns of the domain data type. The value is any variable-free expression (but subqueries are not allowed). The data type of the default expression must match the data type of the domain. If no default value is specified, then the default value is the null value.
The default expression will be used in any insert operation that does not specify a value for the column. If a default value is defined for a particular column, it overrides any default associated with the domain. In turn, the domain default overrides any default value associated with the underlying data type.
CONSTRAINT constraint_name: An optional name for a constraint. If not specified, the system generates a name.
NOT NULL: Values of this domain are not allowed to be null.
NULL: Values of this domain are allowed to be null. This is the default.
This clause is only intended for compatibility with nonstandard SQL databases. Its use is discouraged in new applications.
CHECK (expression): CHECK clauses specify integrity constraints or tests which values of the domain must satisfy. Each constraint must be an expression producing a Boolean result. It should use the name VALUE to refer to the value being tested.
Currently, CHECK expressions cannot contain subqueries nor refer to variables other than VALUE.

EXAMPLES

This example creates the country_code data type and then uses the type in a table definition:

CREATE DOMAIN country_code char(2) NOT NULL; CREATE TABLE countrylist (id integer, country country_code);

COMPATIBILITY

The command CREATE DOMAIN conforms to the SQL standard.

create_group

NAME

CREATE GROUP - define a new user group

SYNOPSIS

CREATE GROUP name [ [ WITH ] option [ ... ] ] where option can be: SYSID gid | USER username [, ...]

DESCRIPTION

CREATE GROUP will create a new group in the database cluster. You must be a database superuser to use this command.

Use ALTER GROUP [alter_group(7)] to change a group`s membership, and DROP GROUP [drop_group(7)] to remove a group.

PARAMETERS

name: The name of the group.
gid: The SYSID clause can be used to choose the PostgreSQL group ID of the new group. It is not necessary to do so, however.
If this is not specified, the highest assigned group ID plus one, starting at 1, will be used as default.
username: A list of users to include in the group. The users must already exist.

EXAMPLES

Create an empty group:

CREATE GROUP staff;

Create a group with members:

CREATE GROUP marketing WITH USER jonathan, david;

COMPATIBILITY

There is no CREATE GROUP statement in the SQL standard. Roles are similar in concept to groups.

create_language

NAME

CREATE LANGUAGE - define a new procedural language

SYNOPSIS

CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name HANDLER call_handler [ VALIDATOR valfunction ]

DESCRIPTION

Using CREATE LANGUAGE, a PostgreSQL user can register a new procedural language with a PostgreSQL database. Subsequently, functions and trigger procedures can be defined in this new language. The user must have the PostgreSQL superuser privilege to register a new language.

CREATE LANGUAGE effectively associates the language name with a call handler that is responsible for executing functions written in the language. Refer to the section called ``User-Defined Functions`` in the documentation for more information about language call handlers.

Note that procedural languages are local to individual databases. To make a language available in all databases by default, it should be installed into the template1 database.

PARAMETERS

TRUSTED: TRUSTED specifies that the call handler for the language is safe, that is, it does not offer an unprivileged user any functionality to bypass access restrictions. If this key word is omitted when registering the language, only users with the PostgreSQL superuser privilege can use this language to create new functions.
PROCEDURAL: This is a noise word.
name: The name of the new procedural language. The language name is case insensitive. The name must be unique among the languages in the database.
For backward compatibility, the name may be enclosed by single quotes.
HANDLER call_handler: call_handler is the name of a previously registered function that will be called to execute the procedural language functions. The call handler for a procedural language must be written in a compiled language such as C with version 1 call convention and registered with PostgreSQL as a function taking no arguments and returning the language_handler type, a placeholder type that is simply used to identify the function as a call handler.
VALIDATOR valfunction: valfunction is the name of a previously registered function that will be called when a new function in the language is created, to validate the new function. If no validator function is specified, then a new function will not be checked when it is created. The validator function must take one argument of type oid, which will be the OID of the to-be-created function, and will typically return void.
A validator function would typically inspect the function body for syntactical correctness, but it can also look at other properties of the function, for example if the language cannot handle certain argument types. To signal an error, the validator function should use the ereport() function. The return value of the function is ignored.

NOTES

This command normally should not be executed directly by users. For the procedural languages supplied in the PostgreSQL distribution, the createlang(1) program should be used, which will also install the correct call handler. (createlang will call CREATE LANGUAGE internally.)

In PostgreSQL versions before 7.3, it was necessary to declare handler functions as returning the placeholder type opaque, rather than language_handler. To support loading of old dump files, CREATE LANGUAGE will accept a function declared as returning opaque, but it will issue a notice and change the function`s declared return type to language_handler.

Use the CREATE FUNCTION [create_function(7)] command to create a new function.

Use DROP LANGUAGE [drop_language(7)], or better yet the droplang(1) program, to drop procedural languages.

The system catalog pg_language (see the chapter called ``System Catalogs`` in the documentation) records information about the currently installed languages. Also createlang has an option to list the installed languages.

The definition of a procedural language cannot be changed once it has been created, with the exception of the privileges.

To be able to use a procedural language, a user must be granted the USAGE privilege. The createlang program automatically grants permissions to everyone if the language is known to be trusted.

EXAMPLES

The following two commands executed in sequence will register a new procedural language and the associated call handler.

CREATE FUNCTION plsample_call_handler() RETURNS language_handler AS `$libdir/plsample` LANGUAGE C; CREATE LANGUAGE plsample HANDLER plsample_call_handler;

COMPATIBILITY

CREATE LANGUAGE is a PostgreSQL extension.

create_operator_class

NAME

CREATE OPERATOR CLASS - define a new operator class

SYNOPSIS

CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type USING index_method AS { OPERATOR strategy_number operator_name [ ( op_type, op_type ) ] [ RECHECK ] | FUNCTION support_number funcname ( argument_type [, ...] ) | STORAGE storage_type } [, ... ]

DESCRIPTION

CREATE OPERATOR CLASS creates a new operator class. An operator class defines how a particular data type can be used with an index. The operator class specifies that certain operators will fill particular roles or ``strategies`` for this data type and this index method. The operator class also specifies the support procedures to be used by the index method when the operator class is selected for an index column. All the operators and functions used by an operator class must be defined before the operator class is created.

If a schema name is given then the operator class is created in the specified schema. Otherwise it is created in the current schema. Two operator classes in the same schema can have the same name only if they are for different index methods.

The user who defines an operator class becomes its owner. Presently, the creating user must be a superuser. (This restriction is made because an erroneous operator class definition could confuse or even crash the server.)

CREATE OPERATOR CLASS does not presently check whether the operator class definition includes all the operators and functions required by the index method. It is the user`s responsibility to define a valid operator class.

Refer to the section called ``Interfacing Extensions to Indexes`` in the documentation for further information.

PARAMETERS

name: The name of the operator class to be created. The name may be schema-qualified.
DEFAULT: If present, the operator class will become the default operator class for its data type. At most one operator class can be the default for a specific data type and index method.
data_type: The column data type that this operator class is for.
index_method: The name of the index method this operator class is for.
strategy_number: The index method`s strategy number for an operator associated with the operator class.
operator_name: The name (optionally schema-qualified) of an operator associated with the operator class.
op_type: The operand data type(s) of an operator, or NONE to signify a left-unary or right-unary operator. The operand data types may be omitted in the normal case where they are the same as the operator class`s data type.
RECHECK: If present, the index is ``lossy`` for this operator, and so the rows retrieved using the index must be rechecked to verify that they actually satisfy the qualification clause involving this operator.
support_number: The index method`s support procedure number for a function associated with the operator class.
funcname: The name (optionally schema-qualified) of a function that is an index method support procedure for the operator class.
argument_types: The parameter data type(s) of the function.
storage_type: The data type actually stored in the index. Normally this is the same as the column data type, but some index methods (only GiST at this writing) allow it to be different. The STORAGE clause must be omitted unless the index method allows a different type to be used.

The OPERATOR, FUNCTION, and STORAGE clauses may appear in any order.

EXAMPLES

The following example command defines a GiST index operator class for the data type _int4 (array of int4). See contrib/intarray/ for the complete example.

CREATE OPERATOR CLASS gist__int_ops DEFAULT FOR TYPE _int4 USING gist AS OPERATOR 3 &&, OPERATOR 6 = RECHECK, OPERATOR 7 @, OPERATOR 8 ~, OPERATOR 20 @@ (_int4, query_int), FUNCTION 1 g_int_consistent (internal, _int4, int4), FUNCTION 2 g_int_union (bytea, internal), FUNCTION 3 g_int_compress (internal), FUNCTION 4 g_int_decompress (internal), FUNCTION 5 g_int_penalty (internal, internal, internal), FUNCTION 6 g_int_picksplit (internal, internal), FUNCTION 7 g_int_same (_int4, _int4, internal);

COMPATIBILITY

CREATE OPERATOR CLASS is a PostgreSQL extension. There is no CREATE OPERATOR CLASS statement in the SQL standard.

create_schema

NAME

CREATE SCHEMA - define a new schema

SYNOPSIS

CREATE SCHEMA schemaname [ AUTHORIZATION username ] [ schema_element [ ... ] ] CREATE SCHEMA AUTHORIZATION username [ schema_element [ ... ] ]

DESCRIPTION

CREATE SCHEMA will enter a new schema into the current database. The schema name must be distinct from the name of any existing schema in the current database.

A schema is essentially a namespace: it contains named objects (tables, data types, functions, and operators) whose names may duplicate those of other objects existing in other schemas. Named objects are accessed either by ``qualifying`` their names with the schema name as a prefix, or by setting a search path that includes the desired schema(s). Unqualified objects are created in the current schema (the one at the front of the search path, which can be determined with the function current_schema).

Optionally, CREATE SCHEMA can include subcommands to create objects within the new schema. The subcommands are treated essentially the same as separate commands issued after creating the schema, except that if the AUTHORIZATION clause is used, all the created objects will be owned by that user.

PARAMETERS

schemaname: The name of a schema to be created. If this is omitted, the user name is used as the schema name.
username: The name of the user who will own the schema. If omitted, defaults to the user executing the command. Only superusers may create schemas owned by users other than themselves.
schema_element: An SQL statement defining an object to be created within the schema. Currently, only CREATE TABLE, CREATE VIEW, and GRANT are accepted as clauses within CREATE SCHEMA. Other kinds of objects may be created in separate commands after the schema is created.

NOTES

To create a schema, the invoking user must have CREATE privilege for the current database. (Of course, superusers bypass this check.)

EXAMPLES

Create a schema:

CREATE SCHEMA myschema;

Create a schema for user joe; the schema will also be named joe:

CREATE SCHEMA AUTHORIZATION joe;

Create a schema and create a table and view within it:

CREATE SCHEMA hollywood CREATE TABLE films (title text, release date, awards text[]) CREATE VIEW winners AS SELECT title, release FROM films WHERE awards IS NOT NULL;

Notice that the individual subcommands do not end with semicolons.

The following is an equivalent way of accomplishing the same result:

CREATE SCHEMA hollywood; CREATE TABLE hollywood.films (title text, release date, awards text[]); CREATE VIEW hollywood.winners AS SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;

COMPATIBILITY

The SQL standard allows a DEFAULT CHARACTER SET clause in CREATE SCHEMA, as well as more subcommand types than are presently accepted by PostgreSQL.

The SQL standard specifies that the subcommands in CREATE SCHEMA may appear in any order. The present PostgreSQL implementation does not handle all cases of forward references in subcommands; it may sometimes be necessary to reorder the subcommands to avoid forward references.

According to the SQL standard, the owner of a schema always owns all objects within it. PostgreSQL allows schemas to contain objects owned by users other than the schema owner. This can happen only if the schema owner grants the CREATE privilege on his schema to someone else.

create_table

NAME

CREATE TABLE - define a new table

SYNOPSIS

CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name ( { column_name data_type [ DEFAULT default_expr ] [ column_constraint [, ... ] ] | table_constraint | LIKE parent_table [ { INCLUDING | EXCLUDING } DEFAULTS ] } [, ... ] ) [ INHERITS ( parent_table [, ... ] ) ] [ WITH OIDS | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] where column_constraint is: [ CONSTRAINT constraint_name ] { NOT NULL | NULL | UNIQUE | PRIMARY KEY | CHECK (expression) | REFERENCES reftable [ ( refcolumn ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE action ] [ ON UPDATE action ] } [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] and table_constraint is: [ CONSTRAINT constraint_name ] { UNIQUE ( column_name [, ... ] ) | PRIMARY KEY ( column_name [, ... ] ) | CHECK ( expression ) | FOREIGN KEY ( column_name [, ... ] ) REFERENCES reftable [ ( refcolumn [, ... ] ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE action ] [ ON UPDATE action ] } [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]

DESCRIPTION

CREATE TABLE will create a new, initially empty table in the current database. The table will be owned by the user issuing the command.

If a schema name is given (for example, CREATE TABLE myschema.mytable ...) then the table is created in the specified schema. Otherwise it is created in the current schema. Temporary tables exist in a special schema, so a schema name may not be given when creating a temporary table. The table name must be distinct from the name of any other table, sequence, index, or view in the same schema.

CREATE TABLE also automatically creates a data type that represents the composite type corresponding to one row of the table. Therefore, tables cannot have the same name as any existing data type in the same schema.

A table cannot have more than 1600 columns. (In practice, the effective limit is lower because of tuple-length constraints).

The optional constraint clauses specify constraints (or tests) that new or updated rows must satisfy for an insert or update operation to succeed. A constraint is an SQL object that helps define the set of valid values in the table in various ways.

There are two ways to define constraints: table constraints and column constraints. A column constraint is defined as part of a column definition. A table constraint definition is not tied to a particular column, and it can encompass more than one column. Every column constraint can also be written as a table constraint; a column constraint is only a notational convenience if the constraint only affects one column.

PARAMETERS

TEMPORARY or TEMP

If specified, the table is created as a temporary table. Temporary tables are automatically dropped at the end of a session, or optionally at the end of the current transaction (see ON COMMIT below). Existing permanent tables with the same name are not visible to the current session while the temporary table exists, unless they are referenced with schema-qualified names. Any indexes created on a temporary table are automatically temporary as well.

Optionally, GLOBAL or LOCAL can be written before TEMPORARY or TEMP. This makes no difference in PostgreSQL, but see Compatibility [create_table(7)].

table_name

The name (optionally schema-qualified) of the table to be created.

column_name

The name of a column to be created in the new table.

data_type

The data type of the column. This may include array specifiers.

DEFAULT

The DEFAULT clause assigns a default data value for the column whose column definition it appears within. The value is any variable-free expression (subqueries and cross-references to other columns in the current table are not allowed). The data type of the default expression must match the data type of the column.

The default expression will be used in any insert operation that does not specify a value for the column. If there is no default for a column, then the default is null.

LIKE parent_table [ { INCLUDING | EXCLUDING } DEFAULTS ]

The LIKE clause specifies a table from which the new table automatically inherits all column names, their data types, and not-null constraints.

Unlike INHERITS, the new table and inherited table are complete decoupled after creation has been completed. Data inserted into the new table will not be reflected into the parent table.

Default expressions for the inherited column definitions will only be included if INCLUDING DEFAULTS is specified. The default is to exclude default expressions.

INHERITS ( parent_table [, ... ] )

The optional INHERITS clause specifies a list of tables from which the new table automatically inherits all columns. If the same column name exists in more than one parent table, an error is reported unless the data types of the columns match in each of the parent tables. If there is no conflict, then the duplicate columns are merged to form a single column in the new table. If the column name list of the new table contains a column that is also inherited, the data type must likewise match the inherited column(s), and the column definitions are merged into one. However, inherited and new column declarations of the same name need not specify identical constraints: all constraints provided from any declaration are merged together and all are applied to the new table. If the new table explicitly specifies a default value for the column, this default overrides any defaults from inherited declarations of the column. Otherwise, any parents that specify default values for the column must all specify the same default, or an error will be reported.

WITH OIDS

WITHOUT OIDS

This optional clause specifies whether rows of the new table should have OIDs (object identifiers) assigned to them. The default is to have OIDs. (If the new table inherits from any tables that have OIDs, then WITH OIDS is forced even if the command says WITHOUT OIDS.)

Specifying WITHOUT OIDS allows the user to suppress generation of OIDs for rows of a table. This may be worthwhile for large tables, since it will reduce OID consumption and thereby postpone wraparound of the 32-bit OID counter. Once the counter wraps around, uniqueness of OIDs can no longer be assumed, which considerably reduces their usefulness. Specifying WITHOUT OIDS also reduces the space required to store the table on disk by 4 bytes per row of the table, thereby improving performance.

CONSTRAINT constraint_name

An optional name for a column or table constraint. If not specified, the system generates a name.

NOT NULL

The column is not allowed to contain null values.

NULL

The column is allowed to contain null values. This is the default.

This clause is only available for compatibility with non-standard SQL databases. Its use is discouraged in new applications.

UNIQUE (column constraint)

UNIQUE ( column_name [, ... ] ) (table constraint)

The UNIQUE constraint specifies that a group of one or more distinct columns of a table may contain only unique values. The behavior of the unique table constraint is the same as that for column constraints, with the additional capability to span multiple columns.

For the purpose of a unique constraint, null values are not considered equal.

Each unique table constraint must name a set of columns that is different from the set of columns named by any other unique or primary key constraint defined for the table. (Otherwise it would just be the same constraint listed twice.)

PRIMARY KEY (column constraint)

PRIMARY KEY ( column_name [, ... ] ) (table constraint)

The primary key constraint specifies that a column or columns of a table may contain only unique (non-duplicate), nonnull values. Technically, PRIMARY KEY is merely a combination of UNIQUE and NOT NULL, but identifying a set of columns as primary key also provides metadata about the design of the schema, as a primary key implies that other tables may rely on this set of columns as a unique identifier for rows.

Only one primary key can be specified for a table, whether as a column constraint or a table constraint.

The primary key constraint should name a set of columns that is different from other sets of columns named by any unique constraint defined for the same table.

CHECK (expression)

The CHECK clause specifies an expression producing a Boolean result which new or updated rows must satisfy for an insert or update operation to succeed. A check constraint specified as a column constraint should reference that column`s value only, while an expression appearing in a table constraint may reference multiple columns.

Currently, CHECK expressions cannot contain subqueries nor refer to variables other than columns of the current row.

REFERENCES reftable [ ( refcolumn ) ] [ MATCH matchtype ] [ ON DELETE action ] [ ON UPDATE action ] (column constraint)

FOREIGN KEY ( column [, ... ] )

Theses clauses specify a foreign key constraint, which specifies that a group of one or more columns of the new table must only contain values which match against values in the referenced column(s) refcolumn of the referenced table reftable. If refcolumn is omitted, the primary key of the reftable is used. The referenced columns must be the columns of a unique or primary key constraint in the referenced table.

A value inserted into these columns is matched against the values of the referenced table and referenced columns using the given match type. There are three match types: MATCH FULL, MATCH PARTIAL, and MATCH SIMPLE, which is also the default. MATCH FULL will not allow one column of a multicolumn foreign key to be null unless all foreign key columns are null. MATCH SIMPLE allows some foreign key columns to be null while other parts of the foreign key are not null. MATCH PARTIAL is not yet implemented.

In addition, when the data in the referenced columns is changed, certain actions are performed on the data in this table`s columns. The ON DELETE clause specifies the action to perform when a referenced row in the referenced table is being deleted. Likewise, the ON UPDATE clause specifies the action to perform when a referenced column in the referenced table is being updated to a new value. If the row is updated, but the referenced column is not actually changed, no action is done. There are the following possible actions for each clause:

NO ACTION: Produce an error indicating that the deletion or update would create a foreign key constraint violation. This is the default action.
RESTRICT: Same as NO ACTION.
CASCADE: Delete any rows referencing the deleted row, or update the value of the referencing column to the new value of the referenced column, respectively.
SET NULL: Set the referencing column values to null.
SET DEFAULT: Set the referencing column values to their default value.

If primary key column is updated frequently, it may be wise to add an index to the foreign key column so that NO ACTION and CASCADE actions associated with the foreign key column can be more efficiently performed.

DEFERRABLE

NOT DEFERRABLE

This controls whether the constraint can be deferred. A constraint that is not deferrable will be checked immediately after every command. Checking of constraints that are deferrable may be postponed until the end of the transaction (using the SET CONSTRAINTS [set_constraints(7)] command). NOT DEFERRABLE is the default. Only foreign key constraints currently accept this clause. All other constraint types are not deferrable.

INITIALLY IMMEDIATE

INITIALLY DEFERRED

If a constraint is deferrable, this clause specifies the default time to check the constraint. If the constraint is INITIALLY IMMEDIATE, it is checked after each statement. This is the default. If the constraint is INITIALLY DEFERRED, it is checked only at the end of the transaction. The constraint check time can be altered with the SET CONSTRAINTS [set_constraints(7)] command.

ON COMMIT

The behavior of temporary tables at the end of a transaction block can be controlled using ON COMMIT. The three options are:

PRESERVE ROWS: No special action is taken at the ends of transactions. This is the default behavior.
DELETE ROWS: All rows in the temporary table will be deleted at the end of each transaction block. Essentially, an automatic truncate(7) is done at each commit.
DROP: The temporary table will be dropped at the end of the current transaction block.

NOTES

*

Whenever an application makes use of OIDs to identify specific rows of a table, it is recommended to create a unique constraint on the oid column of that table, to ensure that OIDs in the table will indeed uniquely identify rows even after counter wraparound. Avoid assuming that OIDs are unique across tables; if you need a database-wide unique identifier, use the combination of tableoid and row OID for the purpose. (It is likely that future PostgreSQL releases will use a separate OID counter for each table, so that it will be necessary, not optional, to include tableoid to have a unique identifier database-wide.)

: Tip: The use of WITHOUT OIDS is not recommended for tables with no primary key, since without either an OID or a unique data key, it is difficult to identify specific rows.

*

PostgreSQL automatically creates an index for each unique constraint and primary key constraint to enforce the uniqueness. Thus, it is not necessary to create an explicit index for primary key columns. (See CREATE INDEX [create_index(7)] for more information.)

*

Unique constraints and primary keys are not inherited in the current implementation. This makes the combination of inheritance and unique constraints rather dysfunctional.

EXAMPLES

Create table films and table distributors:

CREATE TABLE films ( code char(5) CONSTRAINT firstkey PRIMARY KEY, title varchar(40) NOT NULL, did integer NOT NULL, date_prod date, kind varchar(10), len interval hour to minute );

CREATE TABLE distributors ( did integer PRIMARY KEY DEFAULT nextval(`serial`), name varchar(40) NOT NULL CHECK (name <> ``) );

Create a table with a 2-dimensional array:

CREATE TABLE array ( vector int[][] );

Define a unique table constraint for the table films. Unique table constraints can be defined on one or more columns of the table.

CREATE TABLE films ( code char(5), title varchar(40), did integer, date_prod date, kind varchar(10), len interval hour to minute, CONSTRAINT production UNIQUE(date_prod) );

Define a check column constraint:

CREATE TABLE distributors ( did integer CHECK (did > 100), name varchar(40) );

Define a check table constraint:

CREATE TABLE distributors ( did integer, name varchar(40) CONSTRAINT con1 CHECK (did > 100 AND name <> ``) );

Define a primary key table constraint for the table films. Primary key table constraints can be defined on one or more columns of the table.

CREATE TABLE films ( code char(5), title varchar(40), did integer, date_prod date, kind varchar(10), len interval hour to minute, CONSTRAINT code_title PRIMARY KEY(code,title) );

Define a primary key constraint for table distributors. The following two examples are equivalent, the first using the table constraint syntax, the second the column constraint notation.

CREATE TABLE distributors ( did integer, name varchar(40), PRIMARY KEY(did) );

CREATE TABLE distributors ( did integer PRIMARY KEY, name varchar(40) );

This assigns a literal constant default value for the column name, arranges for the default value of column did to be generated by selecting the next value of a sequence object, and makes the default value of modtime be the time at which the row is inserted.

CREATE TABLE distributors ( name varchar(40) DEFAULT `Luso Films`, did integer DEFAULT nextval(`distributors_serial`), modtime timestamp DEFAULT current_timestamp );

Define two NOT NULL column constraints on the table distributors, one of which is explicitly given a name:

CREATE TABLE distributors ( did integer CONSTRAINT no_null NOT NULL, name varchar(40) NOT NULL );

Define a unique constraint for the name column:

CREATE TABLE distributors ( did integer, name varchar(40) UNIQUE );

The above is equivalent to the following specified as a table constraint:

CREATE TABLE distributors ( did integer, name varchar(40), UNIQUE(name) );

COMPATIBILITY

The CREATE TABLE command conforms to SQL92 and to a subset of SQL99, with exceptions listed below.

TEMPORARY TABLES

Although the syntax of CREATE TEMPORARY TABLE resembles that of the SQL standard, the effect is not the same. In the standard, temporary tables are defined just once and automatically exist (starting with empty contents) in every session that needs them. PostgreSQL instead requires each session to issue its own CREATE TEMPORARY TABLE command for each temporary table to be used. This allows different sessions to use the same temporary table name for different purposes, whereas the standard`s approach constrains all instances of a given temporary table name to have the same table structure.

The standard`s definition of the behavior of temporary tables is widely ignored. PostgreSQL`s behavior on this point is similar to that of several other SQL databases.

The standard`s distinction between global and local temporary tables is not in PostgreSQL, since that distinction depends on the concept of modules, which PostgreSQL does not have. For compatibility`s sake, PostgreSQL will accept the GLOBAL and LOCAL keywords in a temporary table declaration, but they have no effect.

The ON COMMIT clause for temporary tables also resembles the SQL standard, but has some differences. If the ON COMMIT clause is omitted, SQL specifies that the default behavior is ON COMMIT DELETE ROWS. However, the default behavior in PostgreSQL is ON COMMIT PRESERVE ROWS. The ON COMMIT DROP option does not exist in SQL.

COLUMN CHECK CONSTRAINTS

The SQL standard says that CHECK column constraints may only refer to the column they apply to; only CHECK table constraints may refer to multiple columns. PostgreSQL does not enforce this restriction; it treats column and table check constraints alike.

NULL ``CONSTRAINT``

The NULL ``constraint`` (actually a non-constraint) is a PostgreSQL extension to the SQL standard that is included for compatibility with some other database systems (and for symmetry with the NOT NULL constraint). Since it is the default for any column, its presence is simply noise.

INHERITANCE

Multiple inheritance via the INHERITS clause is a PostgreSQL language extension. SQL99 (but not SQL92) defines single inheritance using a different syntax and different semantics. SQL99-style inheritance is not yet supported by PostgreSQL.

OBJECT IDS

The PostgreSQL concept of OIDs is not standard.

ZERO-COLUMN TABLES

PostgreSQL allows a table of no columns to be created (for example, CREATE TABLE foo();). This is an extension from the SQL standard, which does not allow zero-column tables. Zero-column tables are not in themselves very useful, but disallowing them creates odd special cases for ALTER TABLE DROP COLUMN, so it seems cleaner to ignore this spec restriction.

create_trigger

NAME

CREATE TRIGGER - define a new trigger

SYNOPSIS

CREATE TRIGGER name { BEFORE | AFTER } { event [ OR ... ] } ON table [ FOR [ EACH ] { ROW | STATEMENT } ] EXECUTE PROCEDURE funcname ( arguments )

DESCRIPTION

CREATE TRIGGER creates a new trigger. The trigger will be associated with the specified table and will execute the specified function func when certain events occur.

The trigger can be specified to fire either before before the operation is attempted on a row (before constraints are checked and the INSERT, UPDATE, or DELETE is attempted) or after the operation has completed (after constraints are checked and the INSERT, UPDATE, or DELETE has completed). If the trigger fires before the event, the trigger may skip the operation for the current row, or change the row being inserted (for INSERT and UPDATE operations only). If the trigger fires after the event, all changes, including the last insertion, update, or deletion, are ``visible`` to the trigger.

A trigger that is marked FOR EACH ROW is called once for every row that the operation modifies. For example, a DELETE that affects 10 rows will cause any ON DELETE triggers on the target relation to be called 10 separate times, once for each deleted row. In contrast, a trigger that is marked FOR EACH STATEMENT only executes once for any given operation, regardless of how many rows it modifies (in particular, an operation that modifies zero rows will still result in the execution of any applicable FOR EACH STATEMENT triggers).

If multiple triggers of the same kind are defined for the same event, they will be fired in alphabetical order by name.

SELECT does not modify any rows so you can not create SELECT triggers. Rules and views are more appropriate in such cases.

Refer to the chapter called ``Triggers`` in the documentation for more information about triggers.

PARAMETERS

name: The name to give the new trigger. This must be distinct from the name of any other trigger for the same table.
BEFORE
AFTER: Determines whether the function is called before or after the event.
event: One of INSERT, UPDATE, or DELETE; this specifies the event that will fire the trigger. Multiple events can be specified using OR.
table: The name (optionally schema-qualified) of the table the trigger is for.
FOR EACH ROW
FOR EACH STATEMENT: This specifies whether the trigger procedure should be fired once for every row affected by the trigger event, or just once per SQL statement. If neither is specified, FOR EACH STATEMENT is the default.
func: A user-supplied function that is declared as taking no arguments and returning type trigger, which is executed when the trigger fires.
arguments: An optional comma-separated list of arguments to be provided to the function when the trigger is executed. The arguments are literal string constants. Simple names and numeric constants may be written here, too, but they will all be converted to strings. Please check the description of the implementation language of the trigger function about how the trigger arguments are accessible within the function; it may be different from normal function arguments.

NOTES

To create a trigger on a table, the user must have the TRIGGER privilege on the table.

In PostgreSQL versions before 7.3, it was necessary to declare trigger functions as returning the placeholder type opaque, rather than trigger. To support loading of old dump files, CREATE TRIGGER will accept a function declared as returning opaque, but it will issue a notice and change the function`s declared return type to trigger.

Use DROP TRIGGER [drop_trigger(7)] to remove a trigger.

EXAMPLES

The chapter called ``Triggers`` in the documentation contains a complete example.

COMPATIBILITY

The CREATE TRIGGER statement in PostgreSQL implements a subset of the SQL99 standard. (There are no provisions for triggers in SQL92.) The following functionality is missing:

*: SQL99 allows triggers to fire on updates to specific columns (e.g., AFTER UPDATE OF col1, col2).
*: SQL99 allows you to define aliases for the ``old`` and ``new`` rows or tables for use in the definition of the triggered action (e.g., CREATE TRIGGER ... ON tablename REFERENCING OLD ROW AS somename NEW ROW AS othername ...). Since PostgreSQL allows trigger procedures to be written in any number of user-defined languages, access to the data is handled in a language-specific way.
*: PostgreSQL only allows the execution of a user-defined function for the triggered action. SQL99 allows the execution of a number of other SQL commands, such as CREATE TABLE as triggered action. This limitation is not hard to work around by creating a user-defined function that executes the desired commands.

SQL99 specifies that multiple triggers should be fired in time-of-creation order. PostgreSQL uses name order, which was judged more convenient to work with.

The ability to specify multiple actions for a single trigger using OR is a PostgreSQL extension of the SQL standard.

create_user

NAME

CREATE USER - define a new database user account

SYNOPSIS

DESCRIPTION

CREATE USER adds a new user to a PostgreSQL database cluster. Refer to the chapters called ``Database Users and Privileges`` and ``Client Authentication`` in the documentation for information about managing users and authentication. You must be a database superuser to use this command.

PARAMETERS

name: The name of the user.
uid: The SYSID clause can be used to choose the PostgreSQL user ID of the user that is being created. This is not normally not necessary, but may be useful if you need to recreate the owner of an orphaned object.
If this is not specified, the highest assigned user ID plus one (with a minimum of 100) will be used as default.
password: Sets the user`s password. If you do not plan to use password authentication you can omit this option, but then the user won`t be able to connect if you decide to switch to password authentication. The password can be set or changed later, using ALTER USER [alter_user(7)].
ENCRYPTED
UNENCRYPTED: These key words control whether the password is stored encrypted in the system catalogs. (If neither is specified, the default behavior is determined by the configuration parameter PASSWORD_ENCRYPTION.) If the presented password string is already in MD5-encrypted format, then it is stored encrypted as-is, regardless of whether ENCRYPTED or UNENCRYPTED is specified (since the system cannot decrypt the specified encrypted password string). This allows reloading of encrypted passwords during dump/restore.
Note that older clients may lack support for the MD5 authentication mechanism that is needed to work with passwords that are stored encrypted.
CREATEDB
NOCREATEDB: These clauses define a user`s ability to create databases. If CREATEDB is specified, the user being defined will be allowed to create his own databases. Using NOCREATEDB will deny a user the ability to create databases. If this clause is omitted, NOCREATEDB is used by default.
CREATEUSER
NOCREATEUSER: These clauses determine whether a user will be permitted to create new users himself. This option will also make the user a superuser who can override all access restrictions. Omitting this clause will set the user`s value of this attribute to be NOCREATEUSER.
groupname: A name of a group into which to insert the user as a new member. Multiple group names may be listed.
abstime: The VALID UNTIL clause sets an absolute time after which the user`s password is no longer valid. If this clause is omitted the login will be valid for all time.

NOTES

Use ALTER USER [alter_user(7)] to change the attributes of a user, and DROP USER [drop_user(7)] to remove a user. Use ALTER GROUP [alter_group(l)] to add the user to groups or remove the user from groups.

PostgreSQL includes a program createuser [createuser(1)] that has the same functionality as CREATE USER (in fact, it calls this command) but can be run from the command shell.

EXAMPLES

Create a user with no password:

CREATE USER jonathan;

Create a user with a password:

CREATE USER davide WITH PASSWORD `jw8s0F4`;

Create a user with a password that is valid until the end of 2004. After one second has ticked in 2005, the password is no longer valid.

CREATE USER miriam WITH PASSWORD `jw8s0F4` VALID UNTIL `2005-01-01`;

Create an account where the user can create databases:

CREATE USER manuel WITH PASSWORD `jw8s0F4` CREATEDB;

COMPATIBILITY

The CREATE USER statement is a PostgreSQL extension. The SQL standard leaves the definition of users to the implementation.

ddp

NAME

ddp - Linux AppleTalk protocol implementation

SYNOPSIS

#include <sys/socket.h>
#include <netatalk/at.h>

ddp_socket = socket(PF_APPLETALK, SOCK_DGRAM, 0);
raw_socket = socket(PF_APPLETALK, SOCK_RAW, protocol);

DESCRIPTION

Linux implements the Appletalk protocols described in Inside Appletalk. Only the DDP layer and AARP are present in the kernel. They are designed to be used via the netatalk protocol libraries. This page documents the interface for those who wish or need to use the DDP layer directly.

The communication between Appletalk and the user program works using a BSD-compatible socket interface. For more information on sockets, see socket(7).

An AppleTalk socket is created by calling the socket(2) function with a PF_APPLETALK socket family argument. Valid socket types are SOCK_DGRAM to open a ddp socket or SOCK_RAW to open a raw socket. protocol is the Appletalk protocol to be received or sent. For SOCK_RAW you must specify ATPROTO_DDP.

Raw sockets may be only opened by a process with effective user id 0 or when the process has the CAP_NET_RAW capability.

ADDRESS FORMAT

An Appletalk socket address is defined as a combination of a network number, a node number, and a port number.

: struct at_addr { u_short s_net; u_char s_node; }; struct sockaddr_atalk { sa_family_t sat_family; /* address family */ u_char sat_port; /* port */ struct at_addr sat_addr; /* net/node */ };

sat_family is always set to AF_APPLETALK. sat_port contains the port. The port numbers below 129 are known as reserved ports. Only processes with the effective user id 0 or the CAP_NET_BIND_SERVICE capability may bind(2) to these sockets. sat_addr is the host address. The net member of struct at_addr contains the host network in network byte order. The value of AT_ANYNET is a wildcard and also implies lqthis network.rq The node member of struct at_addr contains the host node number. The value of AT_ANYNODE is a wildcard and also implies lqthis node.rq The value of ATADDR_BCAST is a link local broadcast address.

SOCKET OPTIONS

No protocol-specific socket options are supported.

SYSCTLS

IP supports a sysctl interface to configure some global AppleTalk parameters. The sysctls can be accessed by reading or writing the /proc/sys/net/atalk/* files or with the sysctl(2) interface.

aarp-expiry-time: The time interval (in seconds) before an AARP cache entry expires.
aarp-resolve-time: The time interval (in seconds) before an AARP cache entry is resolved.
aarp-retransmit-limit: The number of retransmissions of an AARP query before the node is declared dead.
aarp-tick-time: The timer rate (in seconds) for the timer driving AARP.

The default values match the specification and should never need to be changed.

IOCTLS

All ioctls described in socket(7) apply to ddp.

NOTES

Be very careful with the SO_BROADCAST option - it is not privileged in Linux. It is easy to overload the network with careless sending to broadcast addresses.

VERSIONS

Appletalk is supported by Linux 2.0 or higher. The sysctl interface is new in Linux 2.2.

ERRORS

ENOTCONN: The operation is only defined on a connected socket, but the socket wasn`t connected.
EINVAL: Invalid argument passed.
EMSGSIZE: Datagram is bigger than the DDP MTU.
EACCES: The user tried to execute an operation without the necessary permissions. These include sending to a broadcast address without having the broadcast flag set, and trying to bind to a reserved port without effective user id 0 or CAP_NET_BIND_SERVICE.
EADDRINUSE: Tried to bind to an address already in use.
ENOMEM and ENOBUFS: Not enough memory available.
ENOPROTOOPT and EOPNOTSUPP: Invalid socket option passed.
EPERM: User doesn`t have permission to set high priority, make a configuration change, or send signals to the requested process or group,
EADDRNOTAVAIL: A non-existent interface was requested or the requested source address was not local.
EAGAIN: Operation on a nonblocking socket would block.
ESOCKTNOSUPPORT: The socket was unconfigured, or an unknown socket type was requested.
EISCONN: connect(2) was called on an already connected socket.
EALREADY: A connection operation on a non-blocking socket is already in progress.
ECONNABORTED: A connection was closed during an accept(2).
EPIPE: The connection was unexpectedly closed or shut down by the other end.
ENOENT: SIOCGSTAMP was called on a socket where no packet arrived.
EHOSTUNREACH: No routing table entry matches the destination address.
ENODEV: Network device not available or not capable of sending IP.
ENOPKG: A kernel subsystem was not configured.

COMPATIBILITY

The basic AppleTalk socket interface is compatible with netatalk on BSD-derived systems. Many BSD systems fail to check SO_BROADCAST when sending broadcast frames; this can lead to compatibility problems.

The raw socket mode is unique to Linux and exists to support the alternative CAP package and AppleTalk monitoring tools more easily.

BUGS

There are too many inconsistent error values.

The ioctls used to configure routing tables, devices, AARP tables and other devices are not yet described.

declare

NAME

DECLARE - define a cursor

SYNOPSIS

DECLARE name [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR query [ FOR { READ ONLY | UPDATE [ OF column [, ...] ] } ]

DESCRIPTION

DECLARE allows a user to create cursors, which can be used to retrieve a small number of rows at a time out of a larger query. Cursors can return data either in text or in binary format using FETCH [fetch(7)].

Normal cursors return data in text format, the same as a SELECT would produce. Since data is stored natively in binary format, the system must do a conversion to produce the text format. Once the information comes back in text form, the client application may need to convert it to a binary format to manipulate it. In addition, data in the text format is often larger in size than in the binary format. Binary cursors return the data in a binary representation that may be more easily manipulated. Nevertheless, if you intend to display the data as text anyway, retrieving it in text form will save you some effort on the client side.

As an example, if a query returns a value of one from an integer column, you would get a string of 1 with a default cursor whereas with a binary cursor you would get a 4-byte field containing the internal representation of the value (in big-endian byte order).

Binary cursors should be used carefully. Many applications, including psql, are not prepared to handle binary cursors and expect data to come back in the text format.

: Note: When the client application uses the ``extended query`` protocol to issue a FETCH command, the Bind protocol message specifies whether data is to be retrieved in text or binary format. This choice overrides the way that the cursor is defined. The concept of a binary cursor as such is thus obsolete when using extended query protocol --- any cursor can be treated as either text or binary.

PARAMETERS

name: The name of the cursor to be created.
BINARY: Causes the cursor to return data in binary rather than in text format.
INSENSITIVE: Indicates that data retrieved from the cursor should be unaffected by updates to the tables underlying the cursor while the cursor exists. In PostgreSQL, all cursors are insensitive; this key word currently has no effect and is present for compatibility with the SQL standard.
SCROLL
NO SCROLL: SCROLL specifies that the cursor may be used to retrieve rows in a nonsequential fashion (e.g., backward). Depending upon the complexity of the query`s execution plan, specifying SCROLL may impose a performance penalty on the query`s execution time. NO SCROLL specifies that the cursor cannot be used to retrieve rows in a nonsequential fashion.
WITH HOLD
WITHOUT HOLD: WITH HOLD specifies that the cursor may continue to be used after the transaction that created it successfully commits. WITHOUT HOLD specifies that the cursor cannot be used outside of the transaction that created it. If neither WITHOUT HOLD nor WITH HOLD is specified, WITHOUT HOLD is the default.
query: A SELECT command that will provide the rows to be returned by the cursor. Refer to SELECT [select(7)] for further information about valid queries.
FOR READ ONLY
FOR UPDATE: FOR READ ONLY indicates that the cursor will be used in a read-only mode. FOR UPDATE indicates that the cursor will be used to update tables. Since cursor updates are not currently supported in PostgreSQL, specifying FOR UPDATE will cause an error message and specifying FOR READ ONLY has no effect.
column: Column(s) to be updated by the cursor. Since cursor updates are not currently supported in PostgreSQL, the FOR UPDATE clause provokes an error message.

The key words BINARY, INSENSITIVE, and SCROLL may appear in any order.

NOTES

Unless WITH HOLD is specified, the cursor created by this command can only be used within the current transaction. Thus, DECLARE without WITH HOLD is useless outside a transaction block: the cursor would survive only to the completion of the statement. Therefore PostgreSQL reports an error if this command is used outside a transaction block. Use BEGIN [begin(7)], COMMIT [commit(7)] and ROLLBACK [rollback(7)] to define a transaction block.

If WITH HOLD is specified and the transaction that created the cursor successfully commits, the cursor can continue to be accessed by subsequent transactions in the same session. (But if the creating transaction is aborted, the cursor is removed.) A cursor created with WITH HOLD is closed when an explicit CLOSE command is issued on it, or the session ends. In the current implementation, the rows represented by a held cursor are copied into a temporary file or memory area so that they remain available for subsequent transactions.

The SCROLL option should be specified when defining a cursor that will be used to fetch backwards. This is required by the SQL standard. However, for compatibility with earlier versions, PostgreSQL will allow backward fetches without SCROLL, if the cursor`s query plan is simple enough that no extra overhead is needed to support it. However, application developers are advised not to rely on using backward fetches from a cursor that has not been created with SCROLL. If NO SCROLL is specified, then backward fetches are disallowed in any case.

The SQL standard only makes provisions for cursors in embedded SQL. The PostgreSQL server does not implement an OPEN statement for cursors; a cursor is considered to be open when it is declared. However, ECPG, the embedded SQL preprocessor for PostgreSQL, supports the standard SQL cursor conventions, including those involving DECLARE and OPEN statements.

EXAMPLES

To declare a cursor:

DECLARE liahona CURSOR FOR SELECT * FROM films;

See FETCH [fetch(7)] for more examples of cursor usage.

COMPATIBILITY

The SQL standard allows cursors only in embedded SQL and in modules. PostgreSQL permits cursors to be used interactively.

The SQL standard allows cursors to update table data. All PostgreSQL cursors are read only.

Binary cursors are a PostgreSQL extension.

DES.7ssl.php

NAME

Modes of DES - the variants of DES and other crypto algorithms of OpenSSL

DESCRIPTION

Several crypto algorithms for OpenSSL can be used in a number of modes. Those are used for using block ciphers in a way similar to stream ciphers, among other things.

OVERVIEW

Electronic Codebook Mode (ECB)

Normally, this is found as the function algorithm_ecb_encrypt().

*: 64 bits are enciphered at a time.
*: The order of the blocks can be rearranged without detection.
*: The same plaintext block always produces the same ciphertext block (for the same key) making it vulnerable to a `dictionary attack`.
*: An error will only affect one ciphertext block.

Cipher Block Chaining Mode (CBC)

Normally, this is found as the function algorithm_cbc_encrypt(). Be aware that des_cbc_encrypt() is not really DES CBC (it does not update the IV); use des_ncbc_encrypt() instead.

*: a multiple of 64 bits are enciphered at a time.
*: The CBC mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.
*: The chaining operation makes the ciphertext blocks dependent on the current and all preceding plaintext blocks and therefore blocks can not be rearranged.
*: The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.
*: An error will affect the current and the following ciphertext blocks.

Cipher Feedback Mode (CFB)

Normally, this is found as the function algorithm_cfb_encrypt().

*: a number of bits (j) <= 64 are enciphered at a time.
*: The CFB mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.
*: The chaining operation makes the ciphertext variables dependent on the current and all preceding variables and therefore j-bit variables are chained together and can not be rearranged.
*: The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.
*: The strength of the CFB mode depends on the size of k (maximal if j == k). In my implementation this is always the case.
*: Selection of a small value for j will require more cycles through the encipherment algorithm per unit of plaintext and thus cause greater processing overheads.
*: Only multiples of j bits can be enciphered.
*: An error will affect the current and the following ciphertext variables.

Output Feedback Mode (OFB)

Normally, this is found as the function algorithm_ofb_encrypt().

*: a number of bits (j) <= 64 are enciphered at a time.
*: The OFB mode produces the same ciphertext whenever the same plaintext enciphered using the same key and starting variable. More over, in the OFB mode the same key stream is produced when the same key and start variable are used. Consequently, for security reasons a specific start variable should be used only once for a given key.
*: The absence of chaining makes the OFB more vulnerable to specific attacks.
*: The use of different start variables values prevents the same plaintext enciphering to the same ciphertext, by producing different key streams.
*: Selection of a small value for j will require more cycles through the encipherment algorithm per unit of plaintext and thus cause greater processing overheads.
*: Only multiples of j bits can be enciphered.
*: OFB mode of operation does not extend ciphertext errors in the resultant plaintext output. Every bit error in the ciphertext causes only one bit to be in error in the deciphered plaintext.
*: OFB mode is not self-synchronizing. If the two operation of encipherment and decipherment get out of synchronism, the system needs to be re-initialized.
*: Each re-initialization should use a value of the start variable different from the start variable values used before with the same key. The reason for this is that an identical bit stream would be produced each time from the same parameters. This would be susceptible to a `known plaintext` attack.

Triple ECB Mode

Normally, this is found as the function algorithm_ecb3_encrypt().

*: Encrypt with key1, decrypt with key2 and encrypt with key3 again.
*: As for ECB encryption but increases the key length to 168 bits. There are theoretic attacks that can be used that make the effective key length 112 bits, but this attack also requires 2^56 blocks of memory, not very likely, even for the NSA.
*: If both keys are the same it is equivalent to encrypting once with just one key.
*: If the first and last key are the same, the key length is 112 bits. There are attacks that could reduce the effective key strength to only slightly more than 56 bits, but these require a lot of memory.
*: If all 3 keys are the same, this is effectively the same as normal ecb mode.

Triple CBC Mode

Normally, this is found as the function algorithm_ede3_cbc_encrypt().

*: Encrypt with key1, decrypt with key2 and then encrypt with key3.
*: As for CBC encryption but increases the key length to 168 bits with the same restrictions as for triple ecb mode.

NOTES

This text was been written in large parts by Eric Young in his original documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed it to:

AS 2805.5.2 Australian Standard Electronic funds transfer - Requirements for interfaces, Part 5.2: Modes of operation for an n-bit block cipher algorithm Appendix A

des_modes.7ssl.php

NAME

Modes of DES - the variants of DES and other crypto algorithms of OpenSSL

DESCRIPTION

Several crypto algorithms for OpenSSL can be used in a number of modes. Those are used for using block ciphers in a way similar to stream ciphers, among other things.

OVERVIEW

Electronic Codebook Mode (ECB)

Normally, this is found as the function algorithm_ecb_encrypt().

*: 64 bits are enciphered at a time.
*: The order of the blocks can be rearranged without detection.
*: The same plaintext block always produces the same ciphertext block (for the same key) making it vulnerable to a `dictionary attack`.
*: An error will only affect one ciphertext block.

Cipher Block Chaining Mode (CBC)

Normally, this is found as the function algorithm_cbc_encrypt(). Be aware that des_cbc_encrypt() is not really DES CBC (it does not update the IV); use des_ncbc_encrypt() instead.

*: a multiple of 64 bits are enciphered at a time.
*: The CBC mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.
*: The chaining operation makes the ciphertext blocks dependent on the current and all preceding plaintext blocks and therefore blocks can not be rearranged.
*: The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.
*: An error will affect the current and the following ciphertext blocks.

Cipher Feedback Mode (CFB)

Normally, this is found as the function algorithm_cfb_encrypt().

*: a number of bits (j) <= 64 are enciphered at a time.
*: The CFB mode produces the same ciphertext whenever the same plaintext is encrypted using the same key and starting variable.
*: The chaining operation makes the ciphertext variables dependent on the current and all preceding variables and therefore j-bit variables are chained together and can not be rearranged.
*: The use of different starting variables prevents the same plaintext enciphering to the same ciphertext.
*: The strength of the CFB mode depends on the size of k (maximal if j == k). In my implementation this is always the case.
*: Selection of a small value for j will require more cycles through the encipherment algorithm per unit of plaintext and thus cause greater processing overheads.
*: Only multiples of j bits can be enciphered.
*: An error will affect the current and the following ciphertext variables.

Output Feedback Mode (OFB)

Normally, this is found as the function algorithm_ofb_encrypt().

*: a number of bits (j) <= 64 are enciphered at a time.
*: The OFB mode produces the same ciphertext whenever the same plaintext enciphered using the same key and starting variable. More over, in the OFB mode the same key stream is produced when the same key and start variable are used. Consequently, for security reasons a specific start variable should be used only once for a given key.
*: The absence of chaining makes the OFB more vulnerable to specific attacks.
*: The use of different start variables values prevents the same plaintext enciphering to the same ciphertext, by producing different key streams.
*: Selection of a small value for j will require more cycles through the encipherment algorithm per unit of plaintext and thus cause greater processing overheads.
*: Only multiples of j bits can be enciphered.
*: OFB mode of operation does not extend ciphertext errors in the resultant plaintext output. Every bit error in the ciphertext causes only one bit to be in error in the deciphered plaintext.
*: OFB mode is not self-synchronizing. If the two operation of encipherment and decipherment get out of synchronism, the system needs to be re-initialized.
*: Each re-initialization should use a value of the start variable different from the start variable values used before with the same key. The reason for this is that an identical bit stream would be produced each time from the same parameters. This would be susceptible to a `known plaintext` attack.

Triple ECB Mode

Normally, this is found as the function algorithm_ecb3_encrypt().

*: Encrypt with key1, decrypt with key2 and encrypt with key3 again.
*: As for ECB encryption but increases the key length to 168 bits. There are theoretic attacks that can be used that make the effective key length 112 bits, but this attack also requires 2^56 blocks of memory, not very likely, even for the NSA.
*: If both keys are the same it is equivalent to encrypting once with just one key.
*: If the first and last key are the same, the key length is 112 bits. There are attacks that could reduce the effective key strength to only slightly more than 56 bits, but these require a lot of memory.
*: If all 3 keys are the same, this is effectively the same as normal ecb mode.

Triple CBC Mode

Normally, this is found as the function algorithm_ede3_cbc_encrypt().

*: Encrypt with key1, decrypt with key2 and then encrypt with key3.
*: As for CBC encryption but increases the key length to 168 bits with the same restrictions as for triple ecb mode.

NOTES

This text was been written in large parts by Eric Young in his original documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed it to:

AS 2805.5.2 Australian Standard Electronic funds transfer - Requirements for interfaces, Part 5.2: Modes of operation for an n-bit block cipher algorithm Appendix A

drop_aggregate

NAME

DROP AGGREGATE - remove an aggregate function

SYNOPSIS

DROP AGGREGATE name ( type ) [ CASCADE | RESTRICT ]

DESCRIPTION

DROP AGGREGATE will delete an existing aggregate function. To execute this command the current user must be the owner of the aggregate function.

PARAMETERS

name: The name (optionally schema-qualified) of an existing aggregate function.
type: The argument data type of the aggregate function, or * if the function accepts any data type.
CASCADE: Automatically drop objects that depend on the aggregate function.
RESTRICT: Refuse to drop the aggregate function if any objects depend on it. This is the default.

EXAMPLES

To remove the aggregate function myavg for type integer:

DROP AGGREGATE myavg(integer);

COMPATIBILITY

There is no DROP AGGREGATE statement in the SQL standard.

drop_conversion

NAME

DROP CONVERSION - remove a conversion

SYNOPSIS

DROP CONVERSION name [ CASCADE | RESTRICT ]

DESCRIPTION

DROP CONVERSION removes a previously defined conversion. To be able to drop a conversion, you must own the conversion.

PARAMETERS

name: The name of the conversion. The conversion name may be schema-qualified.
CASCADE
RESTRICT: These key words do not have any effect, since there are no dependencies on conversions.

EXAMPLES

To drop the conversion named myname:

DROP CONVERSION myname;

COMPATIBILITY

There is no DROP CONVERSION statement in the SQL standard.

drop_domain

NAME

DROP DOMAIN - remove a domain

SYNOPSIS

DROP DOMAIN name [, ...] [ CASCADE | RESTRICT ]

DESCRIPTION

DROP DOMAIN will remove a domain. Only the owner of a domain can remove it.

PARAMETERS

name: The name (optionally schema-qualified) of an existing domain.
CASCADE: Automatically drop objects that depend on the domain (such as table columns).
RESTRICT: Refuse to drop the domain if any objects depend on it. This is the default.

EXAMPLES

To remove the domain box:

DROP DOMAIN box;

COMPATIBILITY

This command conforms to the SQL standard.

drop_group

NAME

DROP GROUP - remove a user group

SYNOPSIS

DROP GROUP name

DESCRIPTION

DROP GROUP removes the specified group. The users in the group are not deleted.

PARAMETERS

name: The name of an existing group.

EXAMPLES

To drop a group:

DROP GROUP staff;

COMPATIBILITY

There is no DROP GROUP statement in the SQL standard.

drop_language

NAME

DROP LANGUAGE - remove a procedural language

SYNOPSIS

DROP [ PROCEDURAL ] LANGUAGE name [ CASCADE | RESTRICT ]

DESCRIPTION

DROP LANGUAGE will remove the definition of the previously registered procedural language called name.

PARAMETERS

name: The name of an existing procedural language. For backward compatibility, the name may be enclosed by single quotes.
CASCADE: Automatically drop objects that depend on the language (such as functions in the language).
RESTRICT: Refuse to drop the language if any objects depend on it. This is the default.

EXAMPLES

This command removes the procedural language plsample:

DROP LANGUAGE plsample;

COMPATIBILITY

There is no DROP LANGUAGE statement in the SQL standard.

drop_operator_class

NAME

DROP OPERATOR CLASS - remove an operator class

SYNOPSIS

DROP OPERATOR CLASS name USING index_method [ CASCADE | RESTRICT ]

DESCRIPTION

DROP OPERATOR CLASS drops an existing operator class. To execute this command you must be the owner of the operator class.

PARAMETERS

name: The name (optionally schema-qualified) of an existing operator class.
index_method: The name of the index access method the operator class is for.
CASCADE: Automatically drop objects that depend on the operator class.
RESTRICT: Refuse to drop the operator class if any objects depend on it. This is the default.

EXAMPLES

Remove the B-tree operator class widget_ops:

DROP OPERATOR CLASS widget_ops USING btree;

This command will not succeed if there are any existing indexes that use the operator class. Add CASCADE to drop such indexes along with the operator class.

COMPATIBILITY

There is no DROP OPERATOR CLASS statement in the SQL standard.

drop_schema

NAME

DROP SCHEMA - remove a schema

SYNOPSIS

DROP SCHEMA name [, ...] [ CASCADE | RESTRICT ]

DESCRIPTION

DROP SCHEMA removes schemas from the database.

A schema can only be dropped by its owner or a superuser. Note that the owner can drop the schema (and thereby all contained objects) even if he does not own some of the objects within the schema.

PARAMETERS

name: The name of a schema.
CASCADE: Automatically drop objects (tables, functions, etc.) that are contained in the schema.
RESTRICT: Refuse to drop the schema if it contains any objects. This is the default.

EXAMPLES

To remove schema mystuff from the database, along with everything it contains:

DROP SCHEMA mystuff CASCADE;

COMPATIBILITY

DROP SCHEMA is fully conforming with the SQL standard, except that the standard only allows one schema to be dropped per command.

drop_table

NAME

DROP TABLE - remove a table

SYNOPSIS

DROP TABLE name [, ...] [ CASCADE | RESTRICT ]

DESCRIPTION

DROP TABLE removes tables from the database. Only its owner may destroy a table. To empty a table of rows, without destroying the table, use DELETE.

DROP TABLE always removes any indexes, rules, triggers, and constraints that exist for the target table. However, to drop a table that is referenced by a foreign-key constraint of another table, CASCADE must be specified. (CASCADE will remove the foreign-key constraint, not the other table entirely.)

PARAMETERS

name: The name (optionally schema-qualified) of the table to drop.
CASCADE: Automatically drop objects that depend on the table (such as views).
RESTRICT: Refuse to drop the table if any objects depend on it. This is the default.

EXAMPLES

To destroy two tables, films and distributors:

DROP TABLE films, distributors;

COMPATIBILITY

This command conforms to the SQL standard.

drop_type

NAME

DROP TYPE - remove a data type

SYNOPSIS

DROP TYPE name [, ...] [ CASCADE | RESTRICT ]

DESCRIPTION

DROP TYPE will remove a user-defined data type. Only the owner of a type can remove it.

PARAMETERS

name: The name (optionally schema-qualified) of the data type to remove.
CASCADE: Automatically drop objects that depend on the type (such as table columns, functions, operators).
RESTRICT: Refuse to drop the type if any objects depend on it. This is the default.

EXAMPLES

To remove the data type box:

DROP TYPE box;

COMPATIBILITY

This command is similar to the corresponding command in the SQL standard, but note that the CREATE TYPE command and the data type extension mechanisms in PostgreSQL differ from the SQL standard.

drop_view

NAME

DROP VIEW - remove a view

SYNOPSIS

DROP VIEW name [, ...] [ CASCADE | RESTRICT ]

DESCRIPTION

DROP VIEW drops an existing view. To execute this command you must be the owner of the view.

PARAMETERS

name: The name (optionally schema-qualified) of the view to remove.
CASCADE: Automatically drop objects that depend on the view (such as other views).
RESTRICT: Refuse to drop the view if any objects depend on it. This is the default.

EXAMPLES

This command will remove the view called kinds:

DROP VIEW kinds;

COMPATIBILITY

This command conforms to the SQL standard.

execute

NAME

EXECUTE - execute a prepared statement

SYNOPSIS

EXECUTE plan_name [ (parameter [, ...] ) ]

DESCRIPTION

EXECUTE is used to execute a previously prepared statement. Since prepared statements only exist for the duration of a session, the prepared statement must have been created by a PREPARE statement executed earlier in the current session.

If the PREPARE statement that created the statement specified some parameters, a compatible set of parameters must be passed to the EXECUTE statement, or else an error is raised. Note that (unlike functions) prepared statements are not overloaded based on the type or number of their parameters; the name of a prepared statement must be unique within a database session.

For more information on the creation and usage of prepared statements, see PREPARE [prepare(7)].

PARAMETERS

plan_name: The name of the prepared statement to execute.
parameter: The actual value of a parameter to the prepared statement. This must be an expression yielding a value of a type compatible with the data type specified for this parameter position in the PREPARE command that created the prepared statement.

COMPATIBILITY

The SQL standard includes an EXECUTE statement, but it is only for use in embedded SQL. This version of the EXECUTE statement also uses a somewhat different syntax.

fetch

NAME

FETCH - retrieve rows from a query using a cursor

SYNOPSIS

FETCH [ direction { FROM | IN } ] cursorname where direction can be empty or one of: NEXT PRIOR FIRST LAST ABSOLUTE count RELATIVE count count ALL FORWARD FORWARD count FORWARD ALL BACKWARD BACKWARD count BACKWARD ALL

DESCRIPTION

FETCH retrieves rows using a previously-created cursor.

A cursor has an associated position, which is used by FETCH. The cursor position can be before the first row of the query result, on any particular row of the result, or after the last row of the result. When created, a cursor is positioned before the first row. After fetching some rows, the cursor is positioned on the row most recently retrieved. If FETCH runs off the end of the available rows then the cursor is left positioned after the last row, or before the first row if fetching backward. FETCH ALL or FETCH BACKWARD ALL will always leave the cursor positioned after the last row or before the first row.

The forms NEXT, PRIOR, FIRST, LAST, ABSOLUTE, RELATIVE fetch a single row after moving the cursor appropriately. If there is no such row, an empty result is returned, and the cursor is left positioned before the first row or after the last row as appropriate.

The forms using FORWARD and BACKWARD retrieve the indicated number of rows moving in the forward or backward direction, leaving the cursor positioned on the last-returned row (or after/before all rows, if the count exceeds the number of rows available).

RELATIVE 0, FORWARD 0, and BACKWARD 0 all request fetching the current row without moving the cursor, that is, re-fetching the most recently fetched row. This will succeed unless the cursor is positioned before the first row or after the last row; in which case, no row is returned.

PARAMETERS

direction

direction defines the fetch direction and number of rows to fetch. It can be one of the following:

NEXT: Fetch the next row. This is the default if direction is omitted.
PRIOR: Fetch the prior row.
FIRST: Fetch the first row of the query (same as ABSOLUTE 1).
LAST: Fetch the last row of the query (same as ABSOLUTE -1).
ABSOLUTE count: Fetch the count`th row of the query, or the abs(count)`th row from the end if count is negative. Position before first row or after last row if count is out of range; in particular, ABSOLUTE 0 positions before the first row.
RELATIVE count: Fetch the count`th succeeding row, or the abs(count)`th prior row if count is negative. RELATIVE 0 re-fetches the current row, if any.
count: Fetch the next count rows (same as FORWARD count).
ALL: Fetch all remaining rows (same as FORWARD ALL).
FORWARD: Fetch the next row (same as NEXT).
FORWARD count: Fetch the next count rows. FORWARD 0 re-fetches the current row.
FORWARD ALL: Fetch all remaining rows.
BACKWARD: Fetch the prior row (same as PRIOR).
BACKWARD count: Fetch the prior count rows (scanning backwards). BACKWARD 0 re-fetches the current row.
BACKWARD ALL: Fetch all prior rows (scanning backwards).

count: count is a possibly-signed integer constant, determining the location or number of rows to fetch. For FORWARD and BACKWARD cases, specifying a negative count is equivalent to changing the sense of FORWARD and BACKWARD.
cursorname: An open cursor`s name.

OUTPUTS

On successful completion, a FETCH command returns a command tag of the form

FETCH count

The count is the number of rows fetched (possibly zero). Note that in psql, the command tag will not actually be displayed, since psql displays the fetched rows instead.

NOTES

The cursor should be declared with the SCROLL option if one intends to use any variants of FETCH other than FETCH NEXT or FETCH FORWARD with a positive count. For simple queries PostgreSQL will allow backwards fetch from cursors not declared with SCROLL, but this behavior is best not relied on. If the cursor is declared with NO SCROLL, no backward fetches are allowed.

ABSOLUTE fetches are not any faster than navigating to the desired row with a relative move: the underlying implementation must traverse all the intermediate rows anyway. Negative absolute fetches are even worse: the query must be read to the end to find the last row, and then traversed backward from there. However, rewinding to the start of the query (as with FETCH ABSOLUTE 0) is fast.

Updating data via a cursor is currently not supported by PostgreSQL.

DECLARE [declare(7)] is used to define a cursor. Use MOVE [move(7)] to change cursor position without retrieving data.

EXAMPLES

The following example traverses a table using a cursor.

BEGIN WORK; -- Set up a cursor: DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films; -- Fetch the first 5 rows in the cursor liahona: FETCH FORWARD 5 FROM liahona; code | title | did | date_prod | kind | len -------+-------------------------+-----+------------+----------+------- BL101 | The Third Man | 101 | 1949-12-23 | Drama | 01:44 BL102 | The African Queen | 101 | 1951-08-11 | Romantic | 01:43 JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25 P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08 P_302 | Becket | 103 | 1964-02-03 | Drama | 02:28 -- Fetch the previous row: FETCH PRIOR FROM liahona; code | title | did | date_prod | kind | len -------+---------+-----+------------+--------+------- P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08 -- Close the cursor and end the transaction: CLOSE liahona; COMMIT WORK;

COMPATIBILITY

The SQL standard defines FETCH for use in embedded SQL only. This variant of FETCH described here returns the data as if it were a SELECT result rather than placing it in host variables. Other than this point, FETCH is fully upward-compatible with the SQL standard.

The FETCH forms involving FORWARD and BACKWARD, as well as the forms FETCH count and FETCH ALL, in which FORWARD is implicit, are PostgreSQL extensions.

The SQL standard allows only FROM preceding the cursor name; the option to use IN is an extension.

fsf-funding

NAME

fsf-funding - Funding Free Software

DESCRIPTION

Funding Free Software

If you want to have more free software a few years from now, it makes sense for you to help encourage people to contribute funds for its development. The most effective approach known is to encourage commercial redistributors to donate.

Users of free software systems can boost the pace of development by encouraging for-a-fee distributors to donate part of their selling price to free software developers---the Free Software Foundation, and others.

The way to convince distributors to do this is to demand it and expect it from them. So when you compare distributors, judge them partly by how much they give to free software development. Show distributors they must compete to be the one who gives the most.

To make this approach work, you must insist on numbers that you can compare, such as, ``We will donate ten dollars to the Frobnitz project for each disk sold.`` Don`t be satisfied with a vague promise, such as ``A portion of the profits are donated,`` since it doesn`t give a basis for comparison.

Even a precise fraction ``of the profits from this disk`` is not very meaningful, since creative accounting and unrelated business decisions can greatly alter what fraction of the sales price counts as profit. If the price you pay is $50, ten percent of the profit is probably less than a dollar; it might be a few cents, or nothing at all.

Some redistributors do development work themselves. This is useful too; but to keep everyone honest, you need to inquire how much they do, and what kind. Some kinds of development make much more long-term difference than others. For example, maintaining a separate version of a program contributes very little; maintaining the standard version of a program for the whole community contributes much. Easy new ports contribute little, since someone else would surely do them; difficult ports such as adding a new CPU to the GNU Compiler Collection contribute more; major new features or packages contribute the most.

By establishing the idea that supporting further development is ``the proper thing to do`` when distributing free software for a fee, we can assure a steady flow of resources into making more free software.

COPYRIGHT

gimpprint-color

NAME

gimpprint-color - Gimp-Print color balancing

DESCRIPTION

Gimp-Print includes several color balancing controls. These may be used to adjust the original image`s brightness and contrast and gamma, and the density and saturation of the output, as well as the individual cyan, magenta and yellow levels.

COLOR BALANCING

Cyan
Magenta
Yellow: The range of values is 0.0 - 4.0, and defaults to 1.0. These three options allow specification of the cyan, magenta, and yellow levels independently, for rebalancing the levels. Normally, these should be adjusted to yield neutral gray, but they can be used for other effects.
Brightness: The range of values is 0.0 - 2.0, and defaults to 1.0. This adjusts the brightness of the image. 0.0 gives a fully black image; 2.0 gives a fully white image. Values greater than 1 will result in black not being solid and highlights turning white; values less than 1 will result in white not being perfectly clear and shadows turning black.
Contrast: The range of values is 0.0 - 4.0, and defaults to 1.0. Adjust the contrast of the image. 0.0 gives a solid gray for the entire image, the exact gray depending upon the brightness chosen.
Gamma: The range of values is 0.1 - 4.0, and defaults to 1.0. Adjust the gamma of the image, over and above the printer-specific correction. Gamma less than 1.0 will result in a darker image; gamma greater than 1.0 will result in a lighter image. Unlike brightness, gamma adjustment does not change the endpoints; it merely changes the shape of the input->output curve.
Density: The range of values is 0.1 - 2.0, and defaults to 1.0. Adjust the amount of ink deposited on the paper. If you`ve chosen the correct paper type and you`re getting ink bleeding through the paper or puddling, try reducing the density to the lowest value you can while still achieving solid black. If you`re not getting solid black, even with the contrast and brightness at 1.0, try increasing the density.
: All of the printers supported here actually need less than 100% ink density in most cases, so the actual density is something other than the nominal density setting. The effective density setting cannot go above 100%, so if a value specified will result in an excessively high density level, it will be silently limited to 1.0.
Saturation: The range of values is 0.0 - 9.0, and defaults to 1.0. Adjust the brilliance of colors. 0.0 results in pure grayscale; using this with Color=1 is one way of getting grayscale (see below under "Color" for a full discussion). Saturation of less than 1.0 results in more muted colors; saturation of greater than 1.0 results in more vibrant colors. Very high saturation often results in very strange effects, including posterization and banding that might not be expected. For normal purposes, the saturation should generally be less than 1.5.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This manual page was written by Roger Leigh (roger@whinlatter.uklinux.net)

gimpprint-imagetypes

NAME

gimpprint-imagetypes - Gimp-Print image types

DESCRIPTION

Gimp-Print includes several image types which can be used to optimise the dither, depending on the type of image you wish to print.

IMAGE TYPE

Possible values are:

Value	Description

1	Line art (color or gray scale)
2	Primarily solid colors or smooth gradients (color or gray scale)
3	Continuous-tone photographs (color or gray scale)

Option 0 is the fastest. It generates strong, but not particularly accurate, colors. There may be some fairly sharp color transitions in this mode.

Option 1 generates more accurate colors, but is slower.

Option 2 generates the most accurate colors, but is considerably slower.

Note that any of the modes may be used with either color or black & white output. If black and white output is requested, but a color mode used, composite color will be printed. This generally offers smoother tone, but less purity of gray or black, than pure black ink. Furthermore, it is possible to tune the color of the gray (to achieve warmer or cooler effects) using the color controls in this fashion.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This manual page was written by Roger Leigh (roger@whinlatter.uklinux.net)

gimpprint-mediasizes

NAME

gimpprint-mediasizes - Gimp-Print media sizes

DESCRIPTION

Gimp-Print supports many different media (paper) sizes. All of the currently supported media sizes are listed below. The default media size is "Letter".

MEDIA SIZES

Common English paper sizes

Media Size	Description	Comment	x(pt)	y(pt)

Letter	Letter	8.5in x 11in	612	792
Legal	Legal	8.5in x 14in	612	1008
Tabloid	Tabloid	11in x 17in	792	1224
Executive	Executive	7.25in x 10.5in	522	756
Postcard	Postcard	100mm x 147mm	283	416
w216h360	3x5		216	360
w288h432	4x6		288	432
w324h495	Epson 4x6 Photo Paper		324	495
w360h504	5x7		360	504
w360h576	5x8		360	576
8x10	8x10		576	720
Statement	Manual	5.5in x 8.5in	396	612
TabloidExtra	12x18		864	1296
SuperB	13x19		936	1368

Common photographic paper sizes

Media Size	Description	Comment	x(pt)	y(pt)

w576h864	8x12	Sometimes used for 35 mm	576	864
w792h1008	11x14		792	1008
w1152h1440	16x20		1152	1440
w1152h1728	16x24	20x24 for 35 mm	1152	1728
w1440h1728	20x24		1440	1728
w1440h2160	20x30	24x30 for 35 mm	1440	2160
w1728h2160	24x30		1728	2160
w1728h2592	24x36	Sometimes used for 35 mm	1728	2592
w2160h2880	30x40		2160	2880

International Paper Sizes (mostly taken from BS4000:1968)

"A" series: Paper and boards, trimmed sizes.

"A" sizes are in the ratio 1 : sqrt(2). A0 has a total area of 1 square metre. Everything is rounded to the nearest millimetre. Thus, A0 is 841mm x 1189mm. Every other A size is obtained by doubling or halving another A size.

Media Size	Description	Comment	x(pt)	y(pt)

w4768h6749	4A	1682mm x 2378mm	4768	6749
w3370h4768	2A	1189mm x 1682mm	3370	4768
A0	A0	841mm x 1189mm	2384	3370
A1	A1	594mm x 841mm	1684	2384
A2	A2	420mm x 594mm	1191	1684
A3	A3	297mm x 420mm	842	1191
A4	A4	210mm x 297mm	595	842
A5	A5	148mm x 210mm	420	595
A6	A6	105mm x 148mm	297	420
A7	A7	74mm x 105mm	210	297
A8	A8	52mm x 74mm	148	210
A9	A9	37mm x 52mm	105	148
A10	A10	26mm x 37mm	73	105
Stock sizes for normal trims. Allowance for trim is 3 millimetres.
w2437h3458	RA0	860mm x 1220mm	2437	3458
w1729h2437	RA1	610mm x 860mm	1729	2437
w1218h1729	RA2	430mm x 610mm	1218	1729
w864h1218	RA3	305mm x 430mm	864	1218
w609h864	RA4	215mm x 305mm	609	864
Stock sizes for bled work or extra trims.
w2551h3628	SRA0	900mm x 1280mm	2551	3628
w1814h2551	SRA1	640mm x 900mm	1814	2551
w1275h1814	SRA2	450mm x 640mm	1275	1814
w907h1275	SRA3	320mm x 450mm	907	1275
w637h907	SRA4	225mm x 320mm	637	907

"B" series: Posters, wall charts and similar items.

Media Size	Description	Comment	x(pt)	y(pt)

w5669h8016	4B ISO	2000mm x 2828mm	5669	8016
w4008h5669	2B ISO	1414mm x 2000mm	4008	5669
ISOB0	B0 ISO	1000mm x 1414mm	2834	4008
ISOB1	B1 ISO	707mm x 1000mm	2004	2834
ISOB2	B2 ISO	500mm x 707mm	1417	2004
ISOB3	B3 ISO	353mm x 500mm	1000	1417
ISOB4	B4 ISO	250mm x 353mm	708	1000
ISOB5	B5 ISO	176mm x 250mm	498	708
ISOB6	B6 ISO	125mm x 176mm	354	498
ISOB7	B7 ISO	88mm x 125mm	249	354
ISOB8	B8 ISO	62mm x 88mm	175	249
ISOB9	B9 ISO	44mm x 62mm	124	175
ISOB10	B10 ISO	31mm x 44mm	87	124
B0	B0 JIS		2919	4127
B1	B1 JIS		2063	2919
B2	B2 JIS		1459	2063
B3	B3 JIS		1029	1459
B4	B4 JIS		727	1029
B5	B5 JIS		518	727
B6	B6 JIS		362	518
B7	B7 JIS		257	362
B8	B8 JIS		180	257
B9	B9 JIS		127	180
B10	B10 JIS		90	127

"C" series: Envelopes or folders suitable for A size stationery.

Media Size	Description	Comment	x(pt)	y(pt)

C0	C0	917mm x 1297mm	2599	3676
C1	C1	648mm x 917mm	1836	2599
C2	C2	458mm x 648mm	1298	1836
C3	C3	324mm x 458mm	918	1298
C4	C4	229mm x 324mm	649	918
C5	C5	162mm x 229mm	459	649
w354h918	B6-C4	125mm x 324mm	354	918
C6	C6	114mm x 162mm	323	459
DL	DL	110mm x 220mm	311	623
w229h459	C7-6	81mm x 162mm	229	459
C7	C7	81mm x 114mm	229	323
C8	C8	57mm x 81mm	161	229
C9	C9	40mm x 57mm	113	161
C10	C10	28mm x 40mm	79	113

US CAD standard paper sizes

Media Size	Description	Comment	x(pt)	y(pt)

ARCHA	ArchA	9x12in	648	864
ARCHA_transverse	ArchA transverse	12x9in	864	648
ARCHB	ArchB	12x18in	864	1296
ARCHB_transverse	ArchB transverse	18x12in	1296	864
ARCHC	ArchC	18x24in	1296	1728
ARCHC_transverse	ArchC transverse	24x18in	1728	1296
ARCHD	ArchD	24x36in	1728	2592
ARCHD_transverse	ArchD transverse	36x24in	2592	1728
ARCHE	ArchE	36x48in	2592	3456
ARCHE_transverse	ArchE transverse	48x36in	3456	2592

Foolscap

Media Size	Description	Comment	x(pt)	y(pt)

w612h936	American foolscap		612	936
w648h936	European foolscap		648	936

Sizes for book production

The BPIF and the Publishers Association jointly recommend ten standard metric sizes for case-bound titles as follows:

Media Size	Description	Comment	x(pt)	y(pt)

w535h697	Crown Quarto	189mm x 246mm	535	697
w569h731	Large Crown Quarto	201mm x 258mm	569	731
w620h782	Demy Quarto	219mm x 276mm	620	782
w671h884	Royal Quarto	237mm x 312mm	671	884
w348h527	Crown Octavo	123mm x 186mm	348	527
w365h561	Large Crown Octavo	129mm x 198mm	365	561
w391h612	Demy Octavo	138mm x 216mm	391	612
w442h663	Royal Octavo	156mm x 234mm	442	663

Paperback sizes in common usage

Media Size	Description	Comment	x(pt)	y(pt)

w314h504	Small paperback	111mm x 178mm	314	504
w314h513	Penguin small paperback	111mm x 181mm	314	513
w365h561	Penguin large paperback	129mm x 198mm	365	561

Miscellaneous sizes

Media Size	Description	Comment	x(pt)	y(pt)

w283h420	Hagaki Card	100 x 148 mm	283	420
w420h567	Oufuku Card	148 x 200 mm	420	567
w340h666	Long 3	Japanese long envelope #3	340	666
w255h581	Long 4	Japanese long envelope #4	255	581
w680h941	Kaku	Japanese Kaku envelope #4	680	941
COM10	Commercial 10	US Commercial 10 env	297	684
w315h414	A2 Invitation	US A2 invitation	315	414

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This manual page was written by Roger Leigh (roger@whinlatter.uklinux.net)

gimpprint-mediatypes

NAME

gimpprint-mediatypes - Gimp-Print media types

DESCRIPTION

Gimp-Print supports many different media types, which are printer type specific. The option names are case sensitive. Two names are listed for each resolution; the first (short) name is the mediatype, and the second (long) name is descriptive. Not all media types are supported on all printers.

MEDIA TYPES

Epson and Lexmark (other than the 4076) inkjet printers

Media Type	Description

Plain	Plain Paper
PlainFast	Plain Paper Fast Load
Postcard	Postcard
GlossyFilm	Glossy Film
Transparency	Transparencies
Envelope	Envelopes
BackFilm	Back Light Film
Matte	Matte Paper
Inkjet	Inkjet Paper
Coated	Photo Quality Inkjet Paper
GlossyPhoto	Premium Glossy Photo Paper
Luster	Premium Luster Photo Paper
Photo	Photo Paper
Glossy	Photo Quality Glossy Paper
Ilford	Ilford Heavy Paper
Other	Other

We have found that glossy photo papers not specifically designed for Epson printers generally perform poorly in Epson printers. The ink tends to pool on the paper, causing muddy shadows and possibly leaving ink on the printer rollers. Use of the highest quality printing modes (1440x720 highest quality and 2880x720 unidirectional) produces the best result on such papers, probably because printing is slower and there is more time for the ink to dry.

Canon printers

Media Type	Description

Plain	Plain Paper
Transparency	Transparencies
BackFilm	Back Print Film
Fabric	Fabric Sheets
Envelope	Envelope
Coated	High Resolution Paper
TShirt	T-Shirt Transfers
GlossyFilm	High Gloss Film
GlossyPaper	Glossy Photo Paper
GlossyCards	Glossy Photo Cards
GlossyPro	Photo Paper Pro

PCL (Hewlett-Packard and Lexmark 4076) inkjet printers

Media Type	Description

Plain	Plain
Bond	Bond
Premium	Premium
Glossy	Glossy/Photo
Transparency	Transparency
GlossyQD	Quick-dry Photo
TransparencyQD	Quick-dry Transparency

PCL laser printers do not allow specification of any media type.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This manual page was written by Roger Leigh (roger@whinlatter.uklinux.net)

gimpprint-resolutions

NAME

gimpprint-resolutions - Gimp-Print print resolutions

DESCRIPTION

Gimp-Print supports many different resolutions, which are printer type specific. The option names are case sensitive. Not all resolutions are supported on all printers.

PRINT RESOLUTONS

Epson Stylus printers

Within each specified resolution, the quality is generally listed from worst to best (and generally higher quality means lower speed). For example, 360 DPI Unidirectional is usually better than 360 DPI. Characteristics of specific models and individual printers may affect the orderings to some degree; on many printers, with certain papers, unidirectional printing will improve quality substantially more than using an otherwise better quality printing mode.

The difference between different quality settings lies in the number of passes made over each line. "High" and "Highest" quality settings perform more passes, printing fewer dots with each pass over the same line and using different nozzles for each pass. This reduces banding effects, but requires more time.

Interleave modes use algorithms within the printer to generate the sequence of rows printed. These algorithms generally only work well at low printing resolutions. Many printers do not support this kind of printing at resolutions of 720 DPI and above, and some printers that do actually print just one row (using just one nozzle per color) at a time. While this particular use will produce extremely high quality (no banding whatsoever, normally), it is extremely slow and may eventually damage the print head due to ink pooling. All printers that we are aware of have no such trouble at 360 DPI.

We generally recommend the following resolutions for the following purposes:

Resolution	Recommended use

360x90	Fast economy draft output on plain paper (output will be very banded and not very dark).
360x120
180	Economy draft output on plain paper (output will not be very dark).
360x180	Draft output on plain paper (output will not be solidly black); economy draft output on good quality inkjet paper.
360x240
360	Standard quality output on plain paper (output will be solidly black); draft output on good quality inkjet paper.
720x360	High quality output on plain paper; standard output on good quality inkjet paper.
720	Maximum quality on plain paper; high quality on good inkjet paper; proofs on photo-quality paper. On many printers, there will be little difference between this and 720x360 on plain paper.
1440x720	High quality on photo paper; use 1440x720 Highest Quality to reduce microbanding if needed. While this will work on plain paper, it usually offers little improvement over 720 DPI.
2880x720	Highest quality on photo paper. While this may yield slightly improved quality, it will generally not be markedly superior to 1440x720 Highest Quality, except on the Stylus Color 980 and Stylus C70 and C80, where it may yield a noticeable improvement. It takes as long to print as 1440x720 highest quality, but twice as long to generate the output.
1440x1440	An unsupported mode that offers higher quality than 2880x720 for certain types of images on very high quality paper. It does not appear to offer any advantage on smooth tones, but fine detail (particularly vertical, and to a lesser extent near-horizontal) it shows noticeable improvement. It takes as long to print as 2880x720. 1440x1440 highest quality takes twice as long to print.
2880x1440	An unsupported mode that may offer higher quality than 2880x720 for certain types of images on very high quality paper. Experiments conducted thus far demonstrate little if any improvement over 1440x1440. It takes twice as long to print as 2880x720 or 1440x1440, and as long to print as 1440x1440 highest quality.

The following resolutions are supported on printers other than the Stylus Pro (5000, 5500, 7000, 7500, 9000, 9500, and 10000) printers. Resolutions for those printers are listed in a later section. Please see the notes at the end of this section.

Quality	Description	Note

360x90dpi	360 x 90 DPI Fast Economy Draft	(1)
180dpi	180 DPI Economy Draft	(2)
360x180dpi	360 x 180 DPI Draft	(2)
360x180sw	360 x 180 DPI Draft	(3)
360x120dpi	360 x 120 DPI Economy Draft	(4)
360x120sw	360 x 120 DPI Economy Draft	(5)
360x240dpi	360 x 240 DPI Draft	(4)
360x240sw	360 x 240 DPI Draft	(5)
360dpi	360 DPI	(6)
360uni	360 DPI Unidirectional	(6)
360mw	360 DPI Interleave	(6, *)
360mwuni	360 DPI Interleave Unidirectional	(6)
360sw	360 DPI	(7, 17, *)
360swuni	360 DPI Unidirectional	(7, 17)
360hq	360 DPI High Quality	(7, 8, 17)
360hquni	360 DPI High Quality Unidirectional	(7, 8, 17)
720x360sw	720 x 360 DPI	(9, 10)
720x360swuni	720 x 360 DPI Unidirectional	(9, 10)
720mw	720 DPI Interleave	(11)
720mwuni	720 DPI Interleave Unidirectional	(11)
720sw	720 DPI	(9)
720swuni	720 DPI Unidirectional	(9)
720hq	720 DPI High Quality	(9)
720hquni	720 DPI High Quality Unidirectional	(9)
720hq2	720 DPI Highest Quality	(9)
1440x720mw	1440 x 720 DPI Interleave	(12)
1440x720mwuni	1440 x 720 DPI Interleave Unidirectional	(12)
1440x720sw	1440 x 720 DPI	(13)
1440x720swuni	1440 x 720 DPI Unidirectional	(13, 14)
1440x720hq	1440 x 720 DPI Highest Quality	(13)
2880x720sw	2880 x 720 DPI	(15)
2880x720swuni	2880 x 720 DPI Unidirectional	(15)
1440x1440sw	1440 x 1440 DPI	(16)
1440x1440hq2	1440 x 1440 DPI Highest Quality	(16)
2880x1440sw	2880 x 1440 DPI	(16)

*: This resolution is the default on all printers supporting this setting.
1: Works on printers that have a basic vertical spacing of 1/90". This includes the Stylus Color, Stylus Color 440, 460, 600, 640, 660, 670, and 1500, and Stylus Photo, Stylus Photo 700, 720, and EX.
2: Works on most printers that have a basic vertical spacing of 1/90, 1/180, or 1/360 inch. This includes Stylus Color, Stylus Color 440, 460, 600, 640, 660, 670, 800, 850, 900, 980, 1500, 1520, 3000, and Stylus Photo, Stylus Photo 700, 720 and EX.
3: Works on Stylus C70, C80, and C82; and Stylus Photo 950, 960, 2100, and 2200.
4: Works on older printers with dot spacing of 1/120 inch. This includes the Stylus Color Pro, Pro XL, 400, and 500.
5: Works on newer printers with dot spacing of 1/120 inch. This includes the Stylus C20, C40, C41, C42, C60, C61, and C62; the Stylus Color 480, 580, 680, 740, 760, 777, 860, 880, 83, and 1160, and the Stylus Photo 750, 780, 785, 790, 810, 820, 825, 830, 870, 875, 890, 895, 915, 925, 1270, 1280, 1290, and 2000P, and the Stylus Scan 2000 and 2500.
6: Works on all printers that do not support variable drop sizes. This includes the Stylus Color, Stylus Color 400, 440, 460, 500, 600, 640, 660, 800, 850, 1500, 1520, and 3000, Stylus Color Pro, Stylus Color Pro XL, and Stylus Photo, Stylus Photo 700, and EX.
7: Works on all printers that do support variable drop sizes. This includes all supported Epson Stylus printers except for those listed in note (6).
8: Recommended only on processors slower than 200 MHz, the system is heavily loaded with a faster processor, or if problems are experienced at 720x360.
9: Works on all supported printers except for Stylus Color, Stylus Color Pro, Stylus Color Pro XL, Stylus Color 1500, 1520, and 3000.
10: On printers that do not support variable drop size (see note (4)), this will print as fast as 360 DPI, and faster than 360 DPI High Quality. It will take twice as long to generate output, which may be important on a heavily loaded system or a processor slower than 200 MHz.
11: Works on some older printers, including the Stylus Color, Stylus Color 400, 500, 600, 800, 850, 1500, 1520, and 3000, Stylus Color Pro, and Stylus Color Pro XL. Not recommended except for the Stylus Color, Stylus Color 1500, 1520, and 3000.
12: Works on Stylus Color 600, 800, 850, 1520, and 3000. Not recommended unless other 1440x720 modes do not work.
13: Works on all printers that support 1440x720 DPI. This includes all supported printers except for the Stylus Color, Stylus Color Pro, Pro XL, 400, 440, 460, 480, 500, and 1500, and Stylus Photo. In addition, this may not work correctly on Stylus Color 1520 and Stylus Color 3000.
14: This is identical to 1440 x 720 Highest Quality (1440x720hq) on the Stylus Color 900.
15: Works on all printers that support 2880x720 DPI. This includes the Stylus C60, C61, C62, C70, C80, and C82, the Stylus Color 680, 777, 880, 83, and 980, and Stylus Photo 780, 790, 810, 820, 825, 830, 890, 915, 925, 950, 960, 1280, and 1290. This resolution is offered on the Stylus Photo 2100 and 2200, but may not work correctly.
16: Works on Epson Stylus Photo 825, 830, 925, 950, 960, 2100, 2200; Stylus C61, C62, C70, C80, C82 ; Stylus Pro 7600 and 9600. This resolution is not supported by Epson on the C70 and C80, but it works correctly on at least some such printers.
17: These resolutions print at particularly high speed on the Epson Stylus Photo 950, 960, 2100, and 2200 when printing in Four Color Standard or Three Color Composite modes, or when printing in monochrome or grayscale with any ink type other than Two Level Grayscale, Seven Color Photo, or Quadtone.

The Stylus Pro printers (Stylus Pro 5000, 5500, 7000, 7500, 7600, 9000, 9500, 9600, and 10000) support additional interleave modes known as Full Overlap (FOL), Four Pass, and FOL2. The Stylus Pro 5500, 7500, 7600, 9500, 9600, and 10000 additionally have a mode called MW2. These modes can only be used at certain resolutions. Stylus Pro printers support the following resolutions:

Quality	Description

180dpi	180 DPI
360dpi	360 DPI
360uni	360 DPI Unidirectional
360mw	360 DPI Interleave
360mwuni	360 DPI Interleave Unidirectional
360fol	360 DPI Full Overlap
360foluni	360 DPI Full Overlap Unidirectional
360fol2	360 DPI FOL2
360fol2uni	360 DPI FOL2 Unidirectional
360mw2	360 DPI MW2
360mw2uni	360 DPI MW2 Unidirectional
720x360dpi	720 x 360 DPI
720x360uni	720 x 360 DPI Unidirectional
720x360fol	720 x 360 DPI FOL
720x360foluni	720 x 360 DPI FOL Unidirectional
720x360fol2	720 x 360 DPI FOL2
720x360fol2uni	720 x 360 DPI FOL2 Unidirectional
720x360mw2	720 x 360 DPI MW2
720x360mw2uni	720 x 360 DPI MW2 Unidirectional
720dpi	720 DPI
720uni	720 DPI Unidirectional
720mw	720 DPI Interleave
720mwuni	720 DPI Interleave Unidirectional
720fol	720 DPI Full Overlap
720foluni	720 DPI Full Overlap Unidirectional
720fourp	720 DPI Four Pass
720fourpuni	720 DPI Four Pass Unidirectional
1440x720dpi	1440 x 720 DPI
1440x720uni	1440 x 720 DPI Unidirectional
1440x720mw	1440 x 720 DPI Interleave
1440x720mwuni	1440 x 720 DPI Interleave Unidirectional
1440x720fol	1440 x 720 DPI FOL
1440x720foluni	1440 x 720 DPI FOL Unidirectional
1440x720fourp	1440 x 720 DPI Four Pass
1440x720fourpuni	1440 x 720 DPI Four Pass Unidirectional

In addition, the Stylus Pro 7600 and 9600 printers support the following resolutions:

Quality	Description

2880x720dpi	2880 x 720 DPI
2880x720uni	2880 x 720 DPI Unidirectional
2880x720mw	2880 x 720 DPI Interleave
2880x720mwuni	2880 x 720 DPI Interleave Unidirectional
2880x720fol	2880 x 720 DPI FOL
2880x720foluni	2880 x 720 DPI FOL Unidirectional
2880x720fourp	2880 x 720 DPI Four Pass
2880x720fourpuni	2880 x 720 DPI Four Pass Unidirectional
1440x1440dpi	1440 x 1440 DPI
1440x1440uni	1440 x 1440 DPI Unidirectional
1440x1440mw	1440 x 1440 DPI Interleave
1440x1440mwuni	1440 x 1440 DPI Interleave Unidirectional
1440x1440fol	1440 x 1440 DPI FOL
1440x1440foluni	1440 x 1440 DPI FOL Unidirectional
1440x1440fourp	1440 x 1440 DPI Four Pass
1440x1440fourpuni	1440 x 1440 DPI Four Pass Unidirectional
2880x1440dpi	2880 x 1440 DPI
2880x1440uni	2880 x 1440 DPI Unidirectional
2880x1440mw	2880 x 1440 DPI Interleave
2880x1440mwuni	2880 x 1440 DPI Interleave Unidirectional
2880x1440fol	2880 x 1440 DPI FOL
2880x1440foluni	2880 x 1440 DPI FOL Unidirectional
2880x1440fourp	2880 x 1440 DPI Four Pass
2880x1440fourpuni	2880 x 1440 DPI Four Pass Unidirectional

PCL printers (including Hewlett-Packard and Lexmark 4076)

In addition, the Stylus Pro 7600 and 9600 printers support the following resolutions:

Quality	Description

150dpi	150x150 DPI (should work on all printers)
300dpi	300x300 DPI (should work on all printers, C-RET on DJ 850/855/870/890)
600x300dpi	600x300 DPI (DJ 6xx/810/812/840/842/895)
600mono	600x600 DPI monochrome (DJ 6xx (except 69x) /8xx/1100/1120)
600dpi	600x600 DPI (DJ 69x/840/9xx/1220/2000/2500, PhotoSmart P1000/P1100, LJ5/5Si/6)

Note: the higher resolutions of newer PCL printers using "Photo-Ret" are not yet supported.

Lexmark printers (other than the 4076)

Quality	Description

300x600dpi	300 DPI x 600 DPI
600dpi	600 DPI
600hq	600 DPI high quality
600uni	600 DPI Unidirectional
1200dpi	1200 DPI
1200hq	1200 DPI high quality
1200hq2	1200 DPI highest quality
1200uni	1200 DPI Unidirectional
2400x1200dpi	2400 DPI x 1200 DPI (Z52)
2400x1200hq	2400 DPI x 1200 DPI high quality (Z52)
2400x1200hq2	2400 DPI x 1200 DPI highest quality (Z52)

Canon printers

1200 DPI printers (BJC 7000, BJC 7100, BJC 8500):

Quality	Description

300x300dpi	300x300 DPI
300x300dmt	300x300 DPI DMT
600x600dpi	600x600 DPI
600x600dmt	600x600 DPI DMT
1200x600dpi	1200x600 DPI
1200x1200dpi	1200x1200 DPI

1440 DPI printers (BJC 30, BJC 50, BJC 55, BJC 80, BJC 85, BJC 210,
    BJC 240, BJC 250, BJC 1000, BJC 2000, BJC 3000, BJC 4300, BJC
    4400, BJC 6000, BJC 6100, BJC 6200, BJC 6500, BJC 8200, S400,
    S450, S800, S4500):

Quality	Description

360x360dpi	360x360 DPI
360x360dmt	360x360 DPI DMT
720x360dpi	720x360 DPI
720x720dpi	720x720 DPI
1440x720dpi	1440x720 DPI
1440x1440dpi	1440x1440 DPI

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This manual page was written by Roger Leigh (roger@whinlatter.uklinux.net)

gnupg

NAME

GnuPG - The GNU Privacy Guard suite of programs

DESCRIPTION

GnuPG is a set of programs for public key encryption and digital signatures. The program most users will want to use is the OpenPGP command line tool, named gpg. gpgv is a stripped down version of gpg with no encryption functionality, used only to verify signatures against a trusted keyring. There is also a tool called gpgsplit to split OpenPGP messages or keyrings into their component packets. This is mainly useful for seeing how OpenPGP messages are put together.

gpm-types

NAME

This manual page describes what pointer types (mice, tablets, etc) are currently managed by gpm.
The information below is extracted from the texinfo file, which is the preferred source of information.

DESCRIPTION

This manpage describes the various pointer types currently available in gpm. If you look at the source code, you`ll find that pointer-specific code is confined to mice.c (while it used to only include mouse decoders, gpm now supports tablets and touchscreens as well).

The mouse type is specified on command line with the -t option. The option takes an argument, which represents the name of a mouse type. Each type can be associated to different names. For old mouse types, one name is the old selection-compatible name, and another is the XFree name. After version 1.18.1 of gpm, the number of synonyms was made arbitrary and the actual name being used is made available to the function responsible for mouse initialization. Therefore it is possible for a mouse decoder to behave slightly differently according to the name being used for the device (if this feature was already present, we wouldn`t have for example ms+ and ms+lr as different mouse types).

The initialization procedure of each mouse type can also receive extra option, by means of the -o command line option. Since interpretation of the option string is decoder-specific, the allowed options are described in association to each mouse type. When no description of option strings is provided, that means the option string is unused for that mouse type and specifying one generates an error. When the document refer to ``standard serial options`` it means that one of -o dtr, -o rts, -o both can be specified to toggle the control lines of the serial port.

The following mouse type are corrently recognized:

bare Microsoft

The Microsoft protocol, without any extension. It only reports two buttons. If your device has three, you should either try running the mman decoder or msc. In the latter case, you need to tell the mouse to talk msc protocol by toggling the DTR and RTS lines (with one of -o drt, -o rts or -o both) or invoking gpm -t msc while keeping the middle button pressed. Very annoying, indeed. This mouse decoder accepts standard serial options, although they should not be needed.

ms

This is the original Microsoft protocol, with a middle-button extension. Some old two-button devices send some spurious packets which can be misunderstood as middle-button events. If this is your case, use the bare mouse type. Some new two-button devices are ``plug and play``, and they don`t play fair at all; in this case try -t pnp. Many (most) three-button devices that use the microsoft protocol fail to report some middle-button events during mouse motion. Since the protocol does not distinguish between the middle button going up and the middle button going down it would be liable to get out of step, so this decoder declares the middle button to be up whenever the mouse moves. This prevents dragging with the middle button, so you should probably use -t ms+lr instead of this decoder, especially if you want to use X. This mouse decoder accepts standard serial options, although they should not be needed.

ms+

This is the same as -t ms except that the middle button is not reset during mouse motion. So you can drag with the middle button. However, if your mouse exhibits the usual buggy behaviour the decoder is likely to get out of step with reality, thinking the middle button is up when it`s down and vice versa. You should probably use -t ms+lr instead of this decoder. This mouse decoder accepts standard serial options, although they should not be needed.

ms+lr

This is the same as -t ms+ except that there is an additional facility to reset the state of the middle button by pressing the other two buttons together. Do this when the decoder gets into a confused state where it thinks the middle button is up when it`s down and vice versa. (If you get sick of having to do this, please don`t blame gpm; blame your buggy mouse! Note that most three-button mice that do the microsoft protocol can be made to do the MouseSystems protocol instead. The ``3 Button Serial Mouse mini-HOWTO`` has information about this.) This mouse decoder accepts standard serial options, although they should not be needed.

msc MouseSystems

This is the standard protocol for three-button serial devices. Some of such devices only enter MouseSystem mode if the RTS, DTR or both lines are pushed low. Thus, you may try -t msc associated with -o rts, -o dtr or -o both.

mman Mouseman

The protocol used by the new Logitech devices with three buttons. It is backward compatible with the Microsoft protocol, so if your mouse has three buttons and works with -t ms or similar decoders you may try -t mman instead to use the middle button. This mouse decoder accepts standard serial options, although they should not be needed.

sun

The protocol used on Sparc computers and a few others. This mouse decoder accepts standard serial options, although they should not be needed.

mm MMSeries

Title says it all. This mouse decoder accepts standard serial options, although they should not be needed.

logi Logitech

This is the protocol used by old serial Logitech mice.

bm BusMouse

Some bus devices use this protocol, including those produced by Logitech.

ps2 PS/2

The protocol used by most busmice.

ncr

This `type` is able to decode the pointing pen found on some laptops (the NCR 3125 pen)

wacom

The protocol used by the Wacom tablet. Since version 1.18.1 we have a new Wacom decoder, as the old one was not working with new tablets. This decoder was tested with Ultrapad, PenPartner, and Graphire tablets. Options: -o relative (default) for relative mode, -o absolute for absolute mode.

genitizer

The This mouse decoder accepts standard serial options, although they should not be needed.

logim

Used to turn Logitech mice into Mouse-Systems-Compatible. Obviously, it only works with some of the Logitech mice.

pnp

This decoder works with the new mice produces by our friend Bill, and maybe with the old ones as well. The Pnp protocol is hardwired at 1200 baud and is upset by normal initialization, so this is a -t bare decoder with no initialization at all. This mouse decoder accepts standard serial options, although they should not be needed.

ms3

A decoder for the new serial IntelliMouse devices, the ones with three buttons and a protocol incompatible with older ones. The wheel is currently unused.

imps2

``IntelliMouse`` on the ps/2 port. This type can also be used for a generic 2-button ps/2 mouse too, since it will auto-detect the type.

netmouse

Decodes the ``Genius NetMouse`` type of devices on the ps/2 port. For serial ``Netmouse`` devices, use the ``ms3`` decoder.

cal

A decoder of the ``Calcomp UltraSlate device.

calr

Same as above, but in relative mode.

twid

Support for the twiddler keyboard. As of gpm-1.14 this decoder includes a char generator for the text console, but doesn`t yet support X keycodes. If used with -R, gpm will anyway repeat mouse events to the X server. More information about twiddler support can be found in README.twiddler, in the gpm distribution.

syn synaptics

A decoder for the Synaptics TouchPad connected to the serial port. This mouse decoder accepts standard serial options, although they should not be needed.

synps2 synaptics_ps2

Same as above, but for the devices attached to the ps2 port.

brw

A decoder for the Fellowes Browser, a device with 4 buttons and a wheel. This mouse decoder accepts standard serial options, although they should not be needed.

js Joystick

This mouse type uses the joystick device to generate mouse events. It is only available if the header linux/joystick.h is found at compile time. The header (and the device as well) has been introduced only during 2.1 development, and is not present in version 2.0 of the kernel.

summa

This is a decode for the Symmagraphics of Genius tablet, run in absolute mode. A repeater is associated to this decoder, so it can -R summa can be used to generate X events even for other absolute-pointing devices, like touchscreens. To use the repeated data from X, you need a modified xf86Summa.o module.

mtouch

A decoder for the MicroTouch touch screen. Please refer to the file README.microtouch in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file.

gunze

A decoder for the gunze touch screen. Please refer to the file README.gunze in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file. The decoder accepts the following options: smooth=, debounce=. An higher smoothness results in slower motion as well; a smaller smoothness gives faster motion but, obviously, less smooth. The default smoothness is 9. The debounce time is express in milliseconds and is the minimum duration of an up-down event to be taken as a tap. Smaller bounces are ignored.

acecad

The Acecad tablet in absolute mode.

wp wizardpad

Genius WizardPad tablet

FILES

src/mice.c The source file for pointer decoders

groff_man

NAME

groff_man - groff `man` macros to support generation of man pages

SYNOPSIS

groff -man [ options... ] [ files... ]
groff -m man [ options... ] [ files... ]

DESCRIPTION

The man macros used to generate man pages with groff were written by James Clark. This document provides a brief summary of the use of each macro in that package.

OPTIONS

The man macros understand the following command line options (which define various registers).

-rLL=line-length: Set line length. If this option is not given, the line length defaults to 78n in nroff mode and 6.5i in troff mode.
-rLT=title-length: Set title length. If this option is not given, the title length defaults to 78n in nroff mode and 6.5i in troff mode.
-rcR=1: This option (the default if in nroff mode) will create a single, very long page instead of multiple pages. Say -rcR=0 to disable it.
-rC1: If more than one manual page is given on the command line, number the pages continuously, rather than starting each at 1.
-rD1: Double-sided printing. Footers for even and odd pages are formatted differently.
-rPnnn: Enumeration of pages will start with nnn rather than with 1.
-rSxx: Base document font size is xx points (xx can be 10, 11, or 12) rather than 10 points.
-rXnnn: After page nnn, number pages as nnna, nnnb, nnnc, etc. For example, the option `-rX2` will produce the following page numbers: 1, 2, 2a, 2b, 2c, etc.

USAGE

This section describes the available macros for manual pages. For further customization, put additional macros and requests into the file man.local which will be loaded immediately after the man package.

.TH title section [extra1] [extra2] [extra3]

Sets the title of the man page to title and the section to section, which must take on a value between 1 and 8. The value section may also have a string appended, e.g. `.pm`, to indicate a specific subsection of the man pages. Both title and section are positioned at the left and right in the header line (with section in parentheses immediately appended to title. extra1 will be positioned in the middle of the footer line. extra2 will be positioned at the left in the footer line (resp. at the left on even pages and at the right on odd pages if double-sided printing is active). extra3 is centered in the header line.

For HTML output, headers and footers are completely supressed.

Additionally, this macro starts a new page; the new line number is 1 again (except if the `-rC1` option is given on the command line) -- this feature is intended only for formatting multiple man pages; a single man page should contain exactly one TH macro at the beginning of the file.

.SH [text for a heading]

Sets up an unnumbered section heading sticking out to the left. Prints out all the text following SH up to the end of the line (resp. the text in the next input line if there is no argument to SH) in bold face, one size larger than the base document size. Additionally, the left margin for the following text is reset to its default value.

.SS [text for a heading]

Sets up an secondary, unnumbered section heading. Prints out all the text following SS up to the end of the line (resp. the text in the next input line if there is no argument to SS) in bold face, at the same size as the base document size. Additionally, the left margin for the following text is reset to its default value.

.TP [nnn]

Sets up an indented paragraph with label. The indentation is set to nnn if that argument is supplied (the default unit is `n` if omitted), otherwise it is set to the default indentation value. The first input line of text following this macro is interpreted as a string to be printed flush-left, as it is appropriate for a label. It is not interpreted as part of a paragraph, so there is no attempt to fill the first line with text from the following input lines. Nevertheless, if the label is not as wide as the indentation, then the paragraph starts at the same line (but indented), continuing on the following lines. If the label is wider than the indentation, then the descriptive part of the paragraph begins on the line following the label, entirely indented. Note that neither font shape nor font size of the label is set to a default value; on the other hand, the rest of the text will have default font settings. The TP macro is the macro used for the explanations you are just reading.

.LP

.PP

.P

These macros are mutual aliases. Any of them causes a line break at the current position, followed by a vertical space downwards by the amount specified by the PD macro. The font size and shape are reset to the default value (10pt resp. Roman). Finally, the current left margin is restored.

.IP [designator] [nnn]

Sets up an indented paragraph, using designator as a tag to mark its beginning. The indentation is set to nnn if that argument is supplied (default unit is `n`), otherwise the default indentation value is used. Font size and face of the paragraph (but not the designator) are reset to its default values. To start an indented paragraph with a particular indentation but without a designator, use `""` (two doublequotes) as the second argument.

For example, the following paragraphs were all set up with bullets as the designator, using `.IP (bu 4`:

*: IP is one of the three macros used in the man package to format lists.
*: HP is another. This macro produces a paragraph with a left hanging indentation.
*: TP is another. This macro produces an unindented label followed by an indented paragraph.

.HP [nnn]

Sets up a paragraph with hanging left indentation. The indentation is set to nnn if that argument is supplied (default unit is `n`), otherwise the default indentation value is used. Font size and face are reset to its default values. The following paragraph illustrates the effect of this macro with hanging indentation set to 4:

: This is a paragraph following an invocation of the HP macro. As you can see, it produces a paragraph where all lines but the first are indented.

.RS [nnn]

This macro moves the left margin to the right by the value nnn if specified (default unit is `n`); otherwise the default indentation value is used. Calls to the RS macro can be nested.

.RE [nnn]

This macro moves the left margin back to level nnn; if no argument is given, it moves one level back. The first level (i.e., no call to RS yet) has number 1, and each call to RS increases the level by 1.

To summarize, the following macros cause a line break with the insertion of vertical space (which amount can be changed with the PD macro): SH, SS, TP, LP (PP, P), IP, and HP. The macros RS and RE also cause a break but no insertion of vertical space. Finally, the macros SH, SS, LP (PP, P), and RS reset the indentation to its default value.

MACROS TO SET FONTS

The standard font is Roman; the default text size is 10 point.

.SM [text]

Causes the text on the same line or the text on the next input line to appear in a font that is one point size smaller than the default font.

.SB [text]

Causes the text on the same line or the text on the next input line to appear in boldface font, one point size smaller than the default font.

.BI text

Causes text on the same line to appear alternately in bold face and italic. The text must be on the same line as the macro call. Thus

: .BI this "word and" that

would cause `this` and `that` to appear in bold face, while `word and` appears in italics.

.IB text

Causes text to appear alternately in italic and bold face. The text must be on the same line as the macro call.

.RI text

Causes text on the same line to appear alternately in roman and italic. The text must be on the same line as the macro call.

.IR text

Causes text on the same line to appear alternately in italic and roman. The text must be on the same line as the macro call.

.BR text

Causes text on the same line to appear alternately in bold face and roman. The text must be on the same line as the macro call.

.RB text

Causes text on the same line to appear alternately in roman and bold face. The text must be on the same line as the macro call.

.B [text]

Causes text to appear in bold face. If no text is present on the line where the macro is called, then the text of the next input line appears in bold face.

.I [text]

Causes text to appear in italic. If no text is present on the line where the macro is called, then the text of the next input line appears in italic.

MISCELLANEOUS

The default indentation is 7.2n for all output devices except for grohtml which ignores indentation.

.DT: Sets tabs every 0.5 inches. Since this macro is always called during a TH request, it makes sense to call it only if the tab positions have been changed.
.PD [nnn]: Adjusts the empty space before a new paragraph (resp. section). The optional argument gives the amount of space (default units are `v`); without parameter, the value is reset to its default value (1 line for tty devices, 0.4v otherwise). This affects the macros SH, SS, TP, LP (resp. PP and P), IP, and HP.

The following strings are defined:

*S: Switch back to the default font size.
*R: The `registered` sign.
*(Tm: The `trademark` sign.
*(lq
*(rq: Left and right quote. This is equal to `(lq` and `(rq`, respectively.

If a preprocessor like tbl or eqn is needed, it has become usage to make the first line of the man page look like this:

: . word

Note the single space character after the double quote. word consists of letters for the needed preprocessors: `e` for eqn, `r` for refer, and `t` for tbl. Modern implementations of the man program read this first line and automatically call the right preprocessor(s).

FILES

man.tmac
an.tmac: These are wrapper files to call andoc.tmac.
andoc.tmac: This file checks whether the man macros or the mdoc package should be used.
an-old.tmac: All man macros are contained in this file.
man.local: Local changes and customizations should be put into this file.

AUTHOR

This manual page was originally written for the Debian GNU/Linux system by Susan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg <wl@gnu.org>, and is now part of the GNU troff distribution.

groff_me

NAME

groff_me - troff macros for formatting papers

SYNOPSIS

groff -me [ options ] file ...
groff -m me [ options ] file ...

DESCRIPTION

This manual page describes the GNU version of the -me macros, which is part of the groff document formatting system. This version can be used with both GNU troff and Unix troff. This package of troff macro definitions provides a canned formatting facility for tech%nical papers in various formats.

The macro requests are defined below. Many troff requests are unsafe in conjunction with this package, however, these requests may be used with impunity after the first .pp:

: .bp begin new page .br break output line here .sp n insert n spacing lines .ls n (line spacing) n=1 single, n=2 double space .na no alignment of right margin .ce n center next n lines .ul n underline next n lines

Output of the pic, eqn, refer, and tbl preprocessors is acceptable as input.

FILES

/usr/share/groff/1.18.1.1/tmac/me.tmac (a wrapper file for e.tmac)
/usr/share/groff/1.18.1.1/tmac/e.tmac

REQUESTS

This list is incomplete; see The -me Reference Manual for interesting details.

Request     Initial Cause Explanation

            Value   Break

.(c         -       yes   Begin centered block

.(d         -       no    Begin delayed text

.(f         -       no    Begin footnote

.(l         -       yes   Begin list

.(q         -       yes   Begin major quote

.(x x       -       no    Begin indexed item in index
x
.(z         -       no    Begin floating keep

.)c         -       yes   End centered block

.)d         -       yes   End delayed text

.)f         -       yes   End footnote

.)l         -       yes   End list

.)q         -       yes   End major quote

.)x         -       yes   End index item

.)z         -       yes   End floating keep

.++ m H     -       no    Define paper section.
m defines the part of the paper, and can be C (chapter), A (appendix), P (preliminary, e.g., abstract, table of contents, etc.), B (bibliography), RC (chapters renumbered from page one each chapter), or RA (appendix renumbered from page one).
.+c T       -       yes   Begin chapter (or appendix, etc., as
set by .++). T is the chapter title.
.1c         1       yes   One column format on a new page.

.2c         1       yes   Two column format.

.EN         -       yes   Space after equation
produced by eqn or neqn.
.EQ x y     -       yes   Precede equation; break out and
add space. Equation number is y. The optional argument x may be I to indent equation (default), L to left-adjust the equation, or C to center the equation.
.GE         -       yes   End gremlin picture.

.GS         -       yes   Begin gremlin picture.

.PE         -       yes   End pic picture.

.PS         -       yes   Begin pic picture.

.TE         -       yes   End table.

.TH         -       yes   End heading section of table.

.TS x       -       yes   Begin table; if x is
H table has repeated heading.
.b x        no      no    Print
x in boldface; if no argument switch to boldface.
.ba +n      0       yes   Augments the base indent by
n. This indent is used to set the indent on regular text (like paragraphs).
.bc         no      yes   Begin new column

.bi x       no      no    Print
x in bold italics (nofill only)
.bu         -       yes   Begin bulleted paragraph

.bx x       no      no    Print x in a box (nofill only).

.ef `x`y`z` ````    no    Set even footer to x y z

.eh `x`y`z` ````    no    Set even header to x y z

.fo `x`y`z` ````    no    Set footer to x y z

.hx         -       no    Suppress headers and footers on next page.

.he `x`y`z` ````    no    Set header to x y z

.hl         -       yes   Draw a horizontal line

.i x        no      no    Italicize
x; if x missing, italic text follows.
.ip x y     no      yes   Start indented paragraph,
with hanging tag x. Indentation is y ens (default 5).
.lp         yes     yes   Start left-blocked paragraph.

.np         1       yes   Start numbered paragraph.

.of `x`y`z` ````    no    Set odd footer to x y z

.oh `x`y`z` ````    no    Set odd header to x y z

.pd         -       yes   Print delayed text.

.pp         no      yes   Begin paragraph.
First line indented.
.r          yes     no    Roman text follows.

.re         -       no    Reset tabs to default values.

.sh n x     -       yes   Section head follows,
font automatically bold. n is level of section, x is title of section.
.sk         no      no    Leave the next page blank.
Only one page is remembered ahead.
.sm x       -       no    Set
x in a smaller pointsize.
.sz +n      10p     no    Augment the point size by
n points.
.tp         no      yes   Begin title page.

.u x        -       no    Underline argument (even in troff).
(Nofill only).
.uh         -       yes   Like .sh but unnumbered.

.xp x       -       no    Print index
x.

groff_mmse

NAMN

groff_mmse - svenska mm makro för groff

SYNTAX

groff -mmse [ flaggor... ] [ filer... ]

BESKRIVNING

mmse är en svensk variant av mm. Alla texter är översatta. En A4 sida får text som är 13 cm bred, 3.5 cm indragning samt är 28.5 cm hög. Det finns stöd för brevuppställning enligt svensk standard för vänster och högerjusterad text.

COVER kan använda se_ms som argument. Detta ger ett svenskt försättsblad. Se groff_mm(7) för övriga detaljer.

BREV

Tillgängliga brevtyper:

.LT SVV: Vänsterställd löptext med adressat i position T0 (vänsterställt).
.LT SVH: Högerställd löptext med adressat i position T4 (passar fönsterkuvert).

Följande extra LO-variabler används.

.LO DNAMN namn: Anger dokumentets namn.
: .LO MDAT datum Mottagarens datum, anges under Ert datum: (LetMDAT).
: .LO BIL sträng Anger bilaga, nummer eller sträng med Bilaga (LetBIL) som prefix.
: .LO KOMP text Anger kompletteringsuppgift.
: .LO DBET beteckning Anger dokumentbeteckning eller dokumentnummer.
: .LO BET beteckning Anger beteckning (ärendebeteckning i form av diarienummer eller liknande).
: .LO SIDOR antal Anger totala antalet sidor och skrivs ut efter sidnumret inom parenteser.

Om makrot .TP är definierat anropas det efter utskrift av brevhuvudet. Där lägger man lämpligen in postadress och annat som brevfot.

SKRIVET AV

Jörgen Hägg, Lund, Sweden <Jorgen.Hagg@axis.se>

FILER

/usr/share/groff/1.18.1.1/tmac/tmac.mse /usr/share/groff/1.18.1.1/tmac/mm/se_*.cov

SE OCKSÅ

groff(1), troff(1), tbl(1), pic(1), eqn(1)
groff_mm(7)

groff_ms

NAME

groff_ms - groff ms macros

SYNOPSIS

groff -ms [ options... ] [ files... ]
groff -m ms [ options... ] [ files... ]

DESCRIPTION

This manual page describes the GNU version of the ms macros, part of the groff typesetting system. The ms macros are mostly compatible with the documented behavior of the 4.3 BSD Unix ms macros (see Differences from troff ms below for details). The ms macros are suitable for reports, letters, books, and technical documentation.

USAGE

The ms macro package expects files to have a certain amount of structure. The simplest documents can begin with a paragraph macro and consist of text separated by paragraph macros or even blank lines. Longer documents have a structure as follows:

Document type: If you use the RP (report) macro at the beginning of the document, groff prints the cover page information on its own page; otherwise it prints the information on the first page with your document text immediately following. Other document formats found in AT&T troff are specific to AT&T or Berkeley, and are not supported in groff ms.
Format and layout: By setting number registers, you can change your document`s type (font and size), margins, spacing, headers and footers, and footnotes. See Document control registers below for more details.
Cover page: A cover page consists of a title, and optionally the author`s name and institution, an abstract, and the date. See Cover page macros below for more details.
Body: Following the cover page is your document. It consists of paragraphs, headings, and lists.
Table of contents: Longer documents usually include a table of contents, which you can add by placing the TC macro at the end of your document.

Document control registers

The following table lists the document control number registers. For the sake of consistency, set registers related to margins at the beginning of your document, or just after the RP macro.

Margin settings

Reg.	Definition	Effective	Default

PO	Page offset (left margin)	next page	1i
LL	Line length	next para.	6i
LT	Header/footer length	next para.	6i
HM	Top (header) margin	next page	1i
FM	Bottom (footer) margin	next page	1i

Text settings

Reg.	Definition	Effective	Default

PS	Point size	next para.	10p
VS	Line spacing (leading)	next para.	12p

Paragraph settings

Reg.	Definition	Effective	Default

PI	Initial indent	next para.	5n
PD	Space between paragraphs	next para.	0.3v
QI	Quoted paragraph indent	next para.	5n

Footnote settings

Reg.	Definition	Effective	Default

FL	Footnote length	next footnote	LL*5/6
FI	Footnote indent	next footnote	2n
FF	Footnote format	next footnote	0

Other settings

Reg.	Definition	Effective	Default

MINGW	Minimum width between columns	next page	2n

Cover page macros

Use the following macros to create a cover page for your document in the order shown.

.RP [no]: Specifies the report format for your document. The report format creates a separate cover page. With no RP macro, groff prints a subset of the cover page on page~1 of your document.
: If you use the optional no argument, groff prints a title page but does not repeat any of the title page information (title, author, abstract, etc.) on page~1 of the document.
.P1: (P-one) Prints the header on page~1. The default is to suppress the header.
.DA [xxx]: (optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) and in the footers. This is the default for nroff.
.ND [xxx]: (optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) but not in the footers. This is the default for troff.
.TL: Specifies the document title. Groff collects text following the TL macro into the title, until reaching the author name or abstract.
.AU: Specifies the author`s name. You can specify multiple authors by using an AU macro for each author.
.AI: Specifies the author`s institution. You can specify multiple institutions.
.AB [no]: Begins the abstract. The default is to print the word ABSTRACT, centered and in italics, above the text of the abstract. The option no suppresses this heading.
.AE: End the abstract.

Paragraphs

Use the PP macro to create indented paragraphs, and the LP macro to create paragraphs with no initial indent.

The QP macro indents all text at both left and right margins. The effect is identical to the HTML <BLOCKQUOTE> element. The next paragraph or heading returns margins to normal.

The XP macro produces an exdented paragraph. The first line of the paragraph begins at the left margin, and subsequent lines are indented (the opposite of PP).

Headings

Use headings to create a hierarchical structure for your document. The ms macros print headings in bold using the same font family and point size as the body text.

The following heading macros are available:

.NH xx: Numbered heading. The argument xx is either a numeric argument to indicate the level of the heading, or S xx xx "..." to set the section number explicitly. If you specify heading levels out of sequence, such as invoking .NH 3 after .NH 1, groff prints a warning on standard error.
.SH: Unnumbered subheading.

Highlighting

The ms macros provide a variety of methods to highlight or emphasize text:

.B [txt [post [pre]]]

Sets its first argument in bold type. If you specify a second argument, groff prints it in the previous font after the bold text, with no intervening space (this allows you to set punctuation after the highlighted text without highlighting the punctuation). Similarly, it prints the third argument (if any) in the previous font before the first argument. For example,

: .B foo ) (

prints (foo).

If you give this macro no arguments, groff prints all text following in bold until the next highlighting, paragraph, or heading macro.

.R [txt [post [pre]]]

Sets its first argument in roman (or regular) type. It operates similarly to the B macro otherwise.

.I [txt [post [pre]]]

Sets its first argument in italic type. It operates similarly to the B macro otherwise.

.CW [txt [post [pre]]]

Sets its first argument in a constant width face. It operates similarly to the B macro otherwise.

.BI [txt [post [pre]]]

Sets its first argument in bold italic type. It operates similarly to the B macro otherwise.

.BX [txt]

Prints its argument and draws a box around it. If you want to box a string that contains spaces, use a digit-width space ([rs]0).

.UL [txt [post]]

Prints its first argument with an underline. If you specify a second argument, groff prints it in the previous font after the underlined text, with no intervening space.

.LG

Prints all text following in larger type (2~points larger than the current point size) until the next font size, highlighting, paragraph, or heading macro. You can specify this macro multiple times to enlarge the point size as needed.

.SM

Prints all text following in smaller type (2~points smaller than the current point size) until the next type size, highlighting, paragraph, or heading macro. You can specify this macro multiple times to reduce the point size as needed.

.NL

Prints all text following in the normal point size (that is, the value of the PS register).

[rs]*{text[rs]*}

Print the enclosed text as a superscript.

Indents

You may need to indent sections of text. A typical use for indents is to create nested lists and sublists.

Use the RS and RE macros to start and end a section of indented text, respectively. The PI register controls the amount of indent.

You can nest indented sections as deeply as needed by using multiple, nested pairs of RS and RE.

Lists

The IP macro handles duties for all lists. Its syntax is as follows:

.IP [marker [width]]
: The marker is usually a bullet character [rs](bu for unordered lists, a number (or auto-incrementing number register) for numbered lists, or a word or phrase for indented (glossary-style) lists.
: The width specifies the indent for the body of each list item. Once specified, the indent remains the same for all list items in the document until specified again.

Tab stops

Use the ta request to set tab stops as needed. Use the TA macro to reset tabs to the default (every 5n). You can redefine the TA macro to create a different set of default tab stops.

Displays and keeps

Use displays to show text-based examples or figures (such as code listings). Displays turn off filling, so lines of code can be displayed as-is without inserting br requests in between each line. Displays can be kept on a single page, or allowed to break across pages. The following table shows the display types available.

Display macro		Type of display
With keep	No keep

.DS L	.LD		Left-justified.
.DS I [indent]	.ID		Indented (default indent in the DI register).
.DS B	.BD		Block-centered (left-justified, longest line centered).
.DS C	.CD		Centered.
.DS R	.RD		Right-justified.

Use the DE macro to end any display type.

To keep text together on a page, such as a paragraph that refers to a table (or list, or other item) immediately following, use the KS and KE macros. The KS macro begins a block of text to be kept on a single page, and the KE macro ends the block.

You can specify a floating keep using the KF and KE macros. If the keep cannot fit on the current page, groff holds the contents of the keep and allows text following the keep (in the source file) to fill in the remainder of the current page. When the page breaks, whether by an explicit bp request or by reaching the end of the page, groff prints the floating keep at the top of the new page. This is useful for printing large graphics or tables that do not need to appear exactly where specified.

Tables, figures, equations, and references

The -ms macros support the standard groff preprocessors: tbl, pic, eqn, and refer. Mark text meant for preprocessors by enclosing it in pairs of tags as follows:

.TS [H] and .TE: Denotes a table, to be processed by the tbl preprocessor. The optional H~argument instructs groff to create a running header with the information up to the TH macro. Groff prints the header at the beginning of the table; if the table runs onto another page, groff prints the header on the next page as well.
.PS and .PE: Denotes a graphic, to be processed by the pic preprocessor. You can create a pic file by hand, using the AT&T pic manual available on the Web as a reference, or by using a graphics program such as xfig.
.EQ [,align/] and .EN: Denotes an equation, to be processed by the eqn preprocessor. The optional align argument can be C, L, or~I to center (the default), left-justify, or indent the equation.
.[ and .]: Denotes a reference, to be processed by the refer preprocessor. The GNU refer(1) manual page provides a comprehensive reference to the preprocessor and the format of the bibliographic database.

Footnotes

The ms macros provide a flexible footnote system. You can specify a numbered footnote by using the [rs]** escape, followed by the text of the footnote enclosed by FS and FE macros.

You can specify symbolic footnotes by placing the mark character (such as [rs](dg for the dagger character) in the body text, followed by the text of the footnote enclosed by FS [rs](dg and FE macros.

You can control how groff prints footnote numbers by changing the value of the FF register as follows:

0: Prints the footnote number as a superscript; indents the footnote (default).
1: Prints the number followed by a period (like~1.) and indents the footnote.
2: Like~1, without an indent.
3: Like~1, but prints the footnote number as a hanging paragraph.

You can use footnotes safely within keeps and displays, but avoid using numbered footnotes within floating keeps. You can set a second [rs]** between a [rs]** and its corresponding .FS; as long as each .FS occurs after the corresponding [rs]** and the occurrences of .FS are in the same order as the corresponding occurrences of [rs]**.

Headers and footers

There are two ways to define headers and footers:

*

Use the strings LH, CH, and RH to set the left, center, and right headers; use LF, CF, and RF to set the left, center, and right footers. This works best for documents that do not distinguish between odd and even pages.

*

Use the OH and EH macros to define headers for the odd and even pages; and OF and EF macros to define footers for the odd and even pages. This is more flexible than defining the individual strings. The syntax for these macros is as follows:

: .OH `left`center`right`

You can replace the quote (`) marks with any character not appearing in the header or footer text.

Margins

You control margins using a set of number registers. The following table lists the register names and defaults:

Reg.	Definition	Effective	Default

PO	Page offset (left margin)	next page	1i
LL	Line length	next para.	6i
LT	Header/footer length	next para.	6i
HM	Top (header) margin	next page	1i
FM	Bottom (footer) margin	next page	1i

Note that there is no right margin setting. The combination of page offset and line length provide the information necessary to derive the right margin.

Multiple columns

The ms macros can set text in as many columns as will reasonably fit on the page. The following macros are available. All of them force a page break if a multi-column mode is already set. However, if the current mode is single-column, starting a multi-column mode does not force a page break.

.1C: Single-column mode.
.2C: Two-column mode.
.MC [width [gutter]]: Multi-column mode. If you specify no arguments, it is equivalent to the 2C macro. Otherwise, width is the width of each column and gutter is the space between columns. The MINGW number register is the default gutter width.

Creating a table of contents

Wrap text that you want to appear in the table of contents in XS and XE macros. Use the TC macro to print the table of contents at the end of the document, resetting the page number to~i (Roman numeral~1).

You can manually create a table of contents by specifying a page number as the first argument to XS. Add subsequent entries using the XA macro. For example:

.XS 1 Introduction .XA 2 A Brief History of the Universe .XA 729 Details of Galactic Formation ... .XE

Use the PX macro to print a manually-generated table of contents without resetting the page number.

If you give the argument no to either PX or TC, groff suppresses printing the title specified by the [rs]*[TOC] string.

DIFFERENCES FROM troff ms

The groff ms macros are a complete re-implementation, using no original AT&T code. Since they take advantage of the extended features in groff, they cannot be used with AT&T troff. Other differences include:

*: The internals of groff ms differ from the internals of Unix ms. Documents that depend upon implementation details of Unix ms may not format properly with groff ms.
*: The error-handling policy of groff ms is to detect and report errors, rather than silently to ignore them.
*: Bell Labs localisms are not implemented.
*: Berkeley localisms, in particular the TM and CT macros, are not implemented.
*: Groff ms does not work in compatibility mode (e.g. with the -C option).
*: There is no support for typewriter-like devices.
*: Groff ms does not provide cut marks.
*: Multiple line spacing is not supported (use a larger vertical spacing instead).
*: Some Unix ms documentation says that the CW and GW number registers can be used to control the column width and gutter width respectively. These number registers are not used in groff ms.
*: Macros that cause a reset (paragraphs, headings, etc.) may change the indent. Macros that change the indent do not increment or decrement the indent, but rather set it absolutely. This can cause problems for documents that define additional macros of their own. The solution is to use not the in request but instead the RS and RE macros.
*: The number register GS is set to~1 by the groff ms macros, but is not used by the Unix ms macros. Documents that need to determine whether they are being formatted with Unix ms or groff ms should use this number register.

Strings

You can redefine the following strings to adapt the groff ms macros to languages other than English: <CENTER>

String	Default Value

REFERENCES	References
ABSTRACT	ABSTRACT
TOC	Table of Contents
MONTH1	January
MONTH2	February
MONTH3	March
MONTH4	April
MONTH5	May
MONTH6	June
MONTH7	July
MONTH8	August
MONTH9	September
MONTH10	October
MONTH11	November
MONTH12	December

</CENTER>

The [rs]*- string produces an em dash [em] like this.

Text Settings

The FAM string sets the default font family. If this string is undefined at initialization, it is set to Times.

The point size, vertical spacing, and inter-paragraph spacing for footnotes are controlled by the number registers FPS, FVS, and FPD; at initialization these are set to [rs]n(PS-2, [rs]n[FPS]+2, and [rs]n(PD/2 respectively. If any of these registers are defined before initialization, the initialization macro does not change them.

The hyphenation flags (as set by the hy request) are set from the HY register; the default is~14.

Improved accent marks (as originally defined in Berkeley`s ms version) are available by specifying the AM macro at the beginning of your document. You can place an accent over most characters by specifying the string defining the accent directly after the character. For example, n[rs]*~ produces an n with a tilde over it.

NAMING CONVENTIONS

The following conventions are used for names of macros, strings and number registers. External names available to documents that use the groff ms macros contain only uppercase letters and digits.

Internally the macros are divided into modules; naming conventions are as follows:

*: Names used only within one module are of the form module*name.
*: Names used outside the module in which they are defined are of the form module@name.
*: Names associated with a particular environment are of the form environment:name; these are used only within the par module.
*: name does not have a module prefix.
*: Constructed names used to implement arrays are of the form array!index.

Thus the groff ms macros reserve the following names:

*: Names containing the characters *, @, and~:.
*: Names containing only uppercase letters and digits.

FILES

/usr/share/groff/1.18.1.1/tmac/ms.tmac (a wrapper file for s.tmac)
/usr/share/groff/1.18.1.1/tmac/s.tmac

AUTHOR

Original manual page by James Clark et al; rewritten by Larry Kollar (lkollar@despammed.com).

hier

NAME

hier - Description of the file system hierarchy

DESCRIPTION

A typical Linux system has, among others, the following directories:

/: This is the root directory. This is where the whole tree starts.
/bin: This directory contains executable programs which are needed in single user mode and to bring the system up or repair it.
/boot: Contains static files for the boot loader. This directory only holds the files which are needed during the boot process. The map installer and configuration files should go to /sbin and /etc.
/dev: Special or device files, which refer to physical devices. See mknod(1).
/dos: If both MS-DOS and Linux are run on one computer, this is a typical place to mount a DOS file system.
/etc: Contains configuration files which are local to the machine. Some larger software packages, like X11, can have their own subdirectories below /etc. Site-wide configuration files may be placed here or in /usr/etc. Nevertheless, programs should always look for these files in /etc and you may have links for these files to /usr/etc.
/etc/opt: Host-specific configuration files for add-on applications installed in /opt.
/etc/sgml: This directory contains the configuration files for SGML and XML (optional).
/etc/skel: When a new user account is created, files from this directory are usually copied into the user`s home directory.
/etc/X11: Configuration files for the X11 window system (optional).
/home: On machines with home directories for users, these are usually beneath this directory, directly or not. The structure of this directory depends on local administration decisions.
/lib: This directory should hold those shared libraries that are necessary to boot the system and to run the commands in the root filesystem.
/mnt: This directory contains mount points for temporarily mounted filesystems
/opt: This directory should contain add-on packages that contain static files.
/proc: This is a mount point for the proc filesystem, which provides information about running processes and the kernel. This pseudo-file system is described in more detail in proc(5).
/root: This directory is usually the home directory for the root user (optional).
/sbin: Like /bin, this directory holds commands needed to boot the system, but which are usually not executed by normal users.
/tmp: This directory contains temporary files which may be deleted with no notice, such as by a regular job or at system boot up.
/usr: This directory is usually mounted from a separate partition. It should hold only sharable, read-only data, so that it can be mounted by various machines running Linux.
/usr/X11R6: The X-Window system, version 11 release 6 (optional).
/usr/X11R6/bin: Binaries which belong to the X-Windows system; often, there is a symbolic link from the more traditional /usr/bin/X11 to here.
/usr/X11R6/lib: Data files associated with the X-Windows system.
/usr/X11R6/lib/X11: These contain miscellaneous files needed to run X; Often, there is a symbolic link from /usr/lib/X11 to this directory.
/usr/X11R6/include/X11: Contains include files needed for compiling programs using the X11 window system. Often, there is a symbolic link from /usr/include/X11 to this directory.
/usr/bin: This is the primary directory for executable programs. Most programs executed by normal users which are not needed for booting or for repairing the system and which are not installed locally should be placed in this directory.
/usr/bin/X11: is the traditional place to look for X11 executables; on Linux, it usually is a symbolic link to /usr/X11R6/bin.
/usr/dict: Replaced by /usr/share/dict.
/usr/doc: Replaced by /usr/share/doc.
/usr/etc: Site-wide configuration files to be shared between several machines may be stored in this directory. However, commands should always reference those files using the /etc directory. Links from files in /etc should point to the appropriate files in /usr/etc.
/usr/games: Binaries for games and educational programs (optional).
/usr/include: Include files for the C compiler.
/usr/include/X11: Include files for the C compiler and the X-Windows system. This is usually a symbolic link to /usr/X11R6/include/X11.
/usr/include/asm: Include files which declare some assembler functions. This used to be a symbolic link to /usr/src/linux/include/asm.
/usr/include/linux: This contains information which may change from system release to system release and used to be a symbolic link to /usr/src/linux/include/linux to get at operating system specific information.
(Note that one should have include files there that work correctly with the current libc and in user space. However, Linux kernel source is not designed to be used with user programs and does not know anything about the libc you are using. It is very likely that things will break if you let /usr/include/asm and /usr/include/linux point at a random kernel tree. Debian systems don`t do this and use headers from a known good kernel version, provided in the libc*-dev package.)
/usr/include/g++: Include files to use with the GNU C++ compiler.
/usr/lib: Object libraries, including dynamic libraries, plus some executables which usually are not invoked directly. More complicated programs may have whole subdirectories there.
/usr/lib/X11: The usual place for data files associated with X programs, and configuration files for the X system itself. On Linux, it usually is a symbolic link to /usr/X11R6/lib/X11.
/usr/lib/gcc-lib: contains executables and include files for the GNU C compiler, gcc(1).
/usr/lib/groff: Files for the GNU groff document formatting system.
/usr/lib/uucp: Files for uucp(1).
/usr/local: This is where programs which are local to the site typically go.
/usr/local/bin: Binaries for programs local to the site.
/usr/local/doc: Local documentation.
/usr/local/etc: Configuration files associated with locally installed programs.
/usr/local/games: Binaries for locally installed games.
/usr/local/lib: Files associated with locally installed programs.
/usr/local/include: Header files for the local C compiler.
/usr/local/info: Info pages associated with locally installed programs.
/usr/local/man: Man pages associated with locally installed programs.
/usr/local/sbin: Locally installed programs for system administration.
/usr/local/share: Local application data that can be shared among different architectures of the same OS.
/usr/local/src: Source code for locally installed software.
/usr/man: Replaced by /usr/share/man.
/usr/sbin: This directory contains program binaries for system administration which are not essential for the boot process, for mounting /usr, or for system repair.
/usr/share: This directory contains subdirectories with specific application data, that can be shared among different architectures of the same OS. Often one finds stuff here that used to live in /usr/doc or /usr/lib or /usr/man.
/usr/share/dict: Contains the word lists used by spell checkers.
/usr/share/doc: Documentation about installed programs.
/usr/share/games: Static data files for games in /usr/games.
/usr/share/info: Info pages go here.
/usr/share/locale: Locale information goes here.
/usr/share/man: Manpages go here in subdirectories according to the man page sections.
/usr/share/man/<locale>/man[1-9]: These directories contain manual pages for the specific locale in source code form. Systems which use a unique language and code set for all manual pages may omit the <locale> substring.
/usr/share/misc: Miscellaneous data that can be shared among different architectures of the same OS.
/usr/share/nls: The message catalogs for native language support go here.
/usr/share/sgml: Files for SGML and XML.
/usr/share/terminfo: The datebase for terminfo.
/usr/share/tmac: Troff macros that are not distributed with groff.
/usr/share/zoneinfo: Files for timezone information.
/usr/src: Source files for different parts of the system, included with some packages for reference purposes. Don`t work here with your own projects, as files below /usr should be read-only except when installing software.
/usr/src/linux: This was the traditional place for the kernel source. Some distributions put here the source for the default kernel they ship. You should probably use another directory when building your own kernel.
/usr/tmp: Obsolete. This should be a link to /var/tmp. This link is present only for compatibility reasons and shouldn`t be used.
/var: This directory contains files which may change in size, such as spool and log files.
/var/adm: This directory is superseded by /var/log and should be a symbolic link to /var/log.
/var/backups: Reserved for historical reasons.
/var/cache: Data cached for programs.
/var/catman/cat[1-9] or /var/cache/man/cat[1-9]: These directories contain preformatted manual pages according to their man page section. (The use of preformatted manual pages is deprecated.)
/var/cron: Reserved for historical reasons.
/var/lib: Variable state information for programs.
/var/local: Variable data for /usr/local.
/var/lock: Lock files are placed in this directory. The naming convention for device lock files is LCK..<device> where <device> is the device`s name in the filesystem. The format used is that of HDU UUCP lock files, i.e. lock files contain a PID as a 10-byte ASCII decimal number, followed by a newline character.
/var/log: Miscellaneous log files.
/var/opt: Variable data for /opt.
/var/mail: Users` mailboxes. Replaces /var/spool/mail.
/var/msgs: Reserved for historical reasons.
/var/preserve: Reserved for historical reasons.
/var/run: Run-time variable files, like files holding process identifiers (PIDs) and logged user information (utmp). Files in this directory are usually cleared when the system boots.
/var/spool: Spooled (or queued) files for various programs.
/var/spool/at: Spooled jobs for at(1).
/var/spool/cron: Spooled jobs for cron(1).
/var/spool/lpd: Spooled files for printing.
/var/spool/mail: Replaced by /var/mail.
/var/spool/mqueue: Queued outgoing mail.
/var/spool/news: Spool directory for news.
/var/spool/rwho: Spooled files for rwhod(8).
/var/spool/smail: Spooled files for the smail(1) mail delivery program.
/var/spool/uucp: Spooled files for uucp(1).
/var/tmp: Like /tmp, this directory holds temporary files stored for an unspecified duration.
/var/yp: Database files for NIS.

CONFORMS TO

The Filesystem Hierarchy Standard, Version 2.2 <http://www.pathname.com/fhs/>

BUGS

This list is not exhaustive; different systems may be configured differently.

insert

NAME

INSERT - create new rows in a table

SYNOPSIS

INSERT INTO table [ ( column [, ...] ) ] { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) | query }

DESCRIPTION

INSERT allows one to insert new rows into a table. One can insert a single row at a time or several rows as a result of a query.

The columns in the target list may be listed in any order. Each column not present in the target list will be inserted using a default value, either its declared default value or null.

If the expression for each column is not of the correct data type, automatic type conversion will be attempted.

You must have INSERT privilege to a table in order to insert into it. If you use the query clause to insert rows from a query, you also need to have SELECT privilege on any table used in the query.

PARAMETERS

table: The name (optionally schema-qualified) of an existing table.
column: The name of a column in table.
DEFAULT VALUES: All columns will be filled with their default values.
expression: An expression or value to assign to column.
DEFAULT: This column will be filled with its default value.
query: A query (SELECT statement) that supplies the rows to be inserted. Refer to the SELECT statement for a description of the syntax.

OUTPUTS

On successful completion, an INSERT command returns a command tag of the form

INSERT oid count

The count is the number of rows inserted. If count is exactly one, and the target table has OIDs, then oid is the OID assigned to the inserted row. Otherwise oid is zero.

EXAMPLES

Insert a single row into table films:

INSERT INTO films VALUES (`UA502`, `Bananas`, 105, `1971-07-13`, `Comedy`, `82 minutes`);

In this second example, the last column len is omitted and therefore it will have the default value of null:

INSERT INTO films (code, title, did, date_prod, kind) VALUES (`T_601`, `Yojimbo`, 106, `1961-06-16`, `Drama`);

The third example uses the DEFAULT clause for the date columns rather than specifying a value:

INSERT INTO films VALUES (`UA502`, `Bananas`, 105, DEFAULT, `Comedy`, `82 minutes`); INSERT INTO films (code, title, did, date_prod, kind) VALUES (`T_601`, `Yojimbo`, 106, DEFAULT, `Drama`);

This examples inserts several rows into table films from table tmp:

INSERT INTO films SELECT * FROM tmp;

This example inserts into array columns:

-- Create an empty 3x3 gameboard for noughts-and-crosses -- (all of these commands create the same board) INSERT INTO tictactoe (game, board[1:3][1:3]) VALUES (1,`{{"","",""},{},{"",""}}`); INSERT INTO tictactoe (game, board[3][3]) VALUES (2,`{}`); INSERT INTO tictactoe (game, board) VALUES (3,`{{,,},{,,},{,,}}`);

COMPATIBILITY

INSERT conforms fully to the SQL standard. Possible limitations of the query clause are documented under SELECT [select(7)].

ip

NAME

ip - Linux IPv4 protocol implementation

SYNOPSIS

#include <sys/socket.h>
#include <netinet/in.h>

tcp_socket = socket(PF_INET, SOCK_STREAM, 0);
raw_socket = socket(PF_INET, SOCK_RAW, protocol);
udp_socket = socket(PF_INET, SOCK_DGRAM, protocol);

DESCRIPTION

Linux implements the Internet Protocol, version 4, described in RFC791 and RFC1122. ip contains a level 2 multicasting implementation conforming to RFC1112. It also contains an IP router including a packet filter.

The programmer`s interface is BSD sockets compatible. For more information on sockets, see socket(7).

An IP socket is created by calling the socket(2) function as socket(PF_INET, socket_type, protocol). Valid socket types are SOCK_STREAM to open a tcp(7) socket, SOCK_DGRAM to open a udp(7) socket, or SOCK_RAW to open a raw(7) socket to access the IP protocol directly. protocol is the IP protocol in the IP header to be received or sent. The only valid values for protocol are 0 and IPPROTO_TCP for TCP sockets and 0 and IPPROTO_UDP for UDP sockets. For SOCK_RAW you may specify a valid IANA IP protocol defined in RFC1700 assigned numbers.

When a process wants to receive new incoming packets or connections, it should bind a socket to a local interface address using bind(2). Only one IP socket may be bound to any given local (address, port) pair. When INADDR_ANY is specified in the bind call the socket will be bound to all local interfaces. When listen(2) or connect(2) are called on a unbound socket the socket is automatically bound to a random free port with the local address set to INADDR_ANY.

A TCP local socket address that has been bound is unavailable for some time after closing, unless the SO_REUSEADDR flag has been set. Care should be taken when using this flag as it makes TCP less reliable.

ADDRESS FORMAT

An IP socket address is defined as a combination of an IP interface address and a port number. The basic IP protocol does not supply port numbers, they are implemented by higher level protocols like udp(7) and tcp(7). On raw sockets sin_port is set to the IP protocol.

: struct sockaddr_in { sa_family_t sin_family; /* address family: AF_INET */ u_int16_t sin_port; /* port in network byte order */ struct in_addr sin_addr; /* internet address */ }; /* Internet address. */ struct in_addr { u_int32_t s_addr; /* address in network byte order */ };

sin_family is always set to AF_INET. This is required; in Linux 2.2 most networking functions return EINVAL when this setting is missing. sin_port contains the port in network byte order. The port numbers below 1024 are called reserved ports. Only processes with effective user id 0 or the CAP_NET_BIND_SERVICE capability may bind(2) to these sockets. Note that the raw IPv4 protocol as such has no concept of a port, they are only implemented by higher protocols like tcp(7) and udp(7).

sin_addr is the IP host address. The addr member of struct in_addr contains the host interface address in network order. in_addr should be only accessed using the inet_aton(3), inet_addr(3), inet_makeaddr(3) library functions or directly with the name resolver (see gethostbyname(3)). IPv4 addresses are divided into unicast, broadcast and multicast addresses. Unicast addresses specify a single interface of a host, broadcast addresses specify all hosts on a network and multicast addresses address all hosts in a multicast group. Datagrams to broadcast addresses can be only sent or received when the SO_BROADCAST socket flag is set. In the current implementation connection oriented sockets are only allowed to use unicast addresses.

Note that the address and the port are always stored in network order. In particular, this means that you need to call htons(3) on the number that is assigned to a port. All address/port manipulation functions in the standard library work in network order.

There are several special addresses: INADDR_LOOPBACK (127.0.0.1) always refers to the local host via the loopback device; INADDR_ANY (0.0.0.0) means any address for binding; INADDR_BROADCAST (255.255.255.255) means any host and has the same effect on bind as INADDR_ANY for historical reasons.

SOCKET OPTIONS

IP supports some protocol specific socket options that can be set with setsockopt(2) and read with getsockopt(2). The socket option level for IP is SOL_IP. A boolean integer flag is zero when it is false, otherwise true.

IP_OPTIONS

Sets or get the IP options to be sent with every packet from this socket. The arguments are a pointer to a memory buffer containing the options and the option length. The setsockopt(2) call sets the IP options associated with a socket. The maximum option size for IPv4 is 40 bytes. See RFC791 for the allowed options. When the initial connection request packet for a SOCK_STREAM socket contains IP options, the IP options will be set automatically to the options from the initial packet with routing headers reversed. Incoming packets are not allowed to change options after the connection is established. The processing of all incoming source routing options is disabled by default and can be enabled by using the accept_source_route sysctl. Other options like timestamps are still handled. For datagram sockets, IP options can be only set by the local user. Calling getsockopt(2) with IP_OPTIONS puts the current IP options used for sending into the supplied buffer.

IP_PKTINFO

Pass an IP_PKTINFO ancillary message that contains a pktinfo structure that supplies some information about the incoming packet. This only works for datagram oriented sockets. The argument is a flag that tells the socket whether the IP_PKTINFO message should be passed or not. The message itself can only be sent/retrieved as control message with a packet using recvmsg(2) or sendmsg(2).

: struct in_pktinfo { unsigned int ipi_ifindex; /* Interface index */ struct in_addr ipi_spec_dst; /* Local address */ struct in_addr ipi_addr; /* Header Destination address */ };

ipi_ifindex is the unique index of the interface the packet was received on. ipi_spec_dst is the local address of the packet and ipi_addr is the destination address in the packet header. If IP_PKTINFO is passed to sendmsg(2) and ipi_spec_dst is not zero, then it is used as the local source address for the routing table lookup and for setting up IP source route options. When ipi_ifindex is not zero the primary local address of the interface specified by the index overwrites ipi_spec_dst for the routing table lookup.

IP_RECVTOS

If enabled the IP_TOS ancillary message is passed with incoming packets. It contains a byte which specifies the Type of Service/Precedence field of the packet header. Expects a boolean integer flag.

IP_RECVTTL

When this flag is set pass a IP_RECVTTL control message with the time to live field of the received packet as a byte. Not supported for SOCK_STREAM sockets.

IP_RECVOPTS

Pass all incoming IP options to the user in a IP_OPTIONS control message. The routing header and other options are already filled in for the local host. Not supported for SOCK_STREAM sockets.

IP_RETOPTS

Identical to IP_RECVOPTS but returns raw unprocessed options with timestamp and route record options not filled in for this hop.

IP_TOS

Set or receive the Type-Of-Service (TOS) field that is sent with every IP packet originating from this socket. It is used to prioritize packets on the network. TOS is a byte. There are some standard TOS flags defined: IPTOS_LOWDELAY to minimize delays for interactive traffic, IPTOS_THROUGHPUT to optimize throughput, IPTOS_RELIABILITY to optimize for reliability, IPTOS_MINCOST should be used for "filler data" where slow transmission doesn`t matter. At most one of these TOS values can be specified. Other bits are invalid and shall be cleared. Linux sends IPTOS_LOWDELAY datagrams first by default, but the exact behaviour depends on the configured queueing discipline. Some high priority levels may require an effective user id of 0 or the CAP_NET_ADMIN capability. The priority can also be set in a protocol independent way by the (SOL_SOCKET, SO_PRIORITY) socket option (see socket(7)).

IP_TTL

Set or retrieve the current time to live field that is send in every packet send from this socket.

IP_HDRINCL

If enabled the user supplies an ip header in front of the user data. Only valid for SOCK_RAW sockets. See raw(7) for more information. When this flag is enabled the values set by IP_OPTIONS, IP_TTL and IP_TOS are ignored.

IP_RECVERR (defined in <linux/errqueue.h>)

Enable extended reliable error message passing. When enabled on a datagram socket all generated errors will be queued in a per-socket error queue. When the user receives an error from a socket operation the errors can be received by calling recvmsg(2) with the MSG_ERRQUEUE flag set. The sock_extended_err structure describing the error will be passed in a ancillary message with the type IP_RECVERR and the level SOL_IP. This is useful for reliable error handling on unconnected sockets. The received data portion of the error queue contains the error packet.

The IP_RECVERR control message contains a sock_extended_err structure:

: #define SO_EE_ORIGIN_NONE 0 #define SO_EE_ORIGIN_LOCAL 1 #define SO_EE_ORIGIN_ICMP 2 #define SO_EE_ORIGIN_ICMP6 3 struct sock_extended_err { u_int32_t ee_errno; /* error number */ u_int8_t ee_origin; /* where the error originated */ u_int8_t ee_type; /* type */ u_int8_t ee_code; /* code */ u_int8_t ee_pad; u_int32_t ee_info; /* additional information */ u_int32_t ee_data; /* other data */ /* More data may follow */ }; struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);

ee_errno contains the errno number of the queued error. ee_origin is the origin code of where the error originated. The other fields are protocol specific. The macro SO_EE_OFFENDER returns a pointer to the address of the network object where the error originated from given a pointer to the ancillary message. If this address is not known, the sa_family member of the sockaddr contains AF_UNSPEC and the other fields of the sockaddr are undefined.

IP uses the sock_extended_err structure as follows: ee_origin is set to SO_EE_ORIGIN_ICMP for errors received as an ICMP packet, or SO_EE_ORIGIN_LOCAL for locally generated errors. Unknown values should be ignored. ee_type and ee_code are set from the type and code fields of the ICMP header. ee_info contains the discovered MTU for EMSGSIZE errors. The message also contains the sockaddr_in of the node caused the error, which can be accessed with the SO_EE_OFFENDER macro. The sin_family field of the SO_EE_OFFENDER address is AF_UNSPEC when the source was unknown. When the error originated from the network, all IP options (IP_OPTIONS, IP_TTL, etc.) enabled on the socket and contained in the error packet are passed as control messages. The payload of the packet causing the error is returned as normal payload. Note that TCP has no error queue; MSG_ERRQUEUE is illegal on SOCK_STREAM sockets. Thus all errors are returned by socket function return or SO_ERROR only.

For raw sockets, IP_RECVERR enables passing of all received ICMP errors to the application, otherwise errors are only reported on connected sockets

It sets or retrieves an integer boolean flag. IP_RECVERR defaults to off.

IP_MTU_DISCOVER

Sets or receives the Path MTU Discovery setting for a socket. When enabled, Linux will perform Path MTU Discovery as defined in RFC1191 on this socket. The don`t fragment flag is set on all outgoing datagrams. The system-wide default is controlled by the ip_no_pmtu_disc sysctl for SOCK_STREAM sockets, and disabled on all others. For non SOCK_STREAM sockets it is the user`s responsibility to packetize the data in MTU sized chunks and to do the retransmits if necessary. The kernel will reject packets that are bigger than the known path MTU if this flag is set (with EMSGSIZE ).

Path MTU discovery flags	Meaning
IP_PMTUDISC_WANT	Use per-route settings.
IP_PMTUDISC_DONT	Never do Path MTU Discovery.
IP_PMTUDISC_DO	Always do Path MTU Discovery.

When PMTU discovery is enabled the kernel automatically keeps track of the path MTU per destination host. When it is connected to a specific peer with connect(2) the currently known path MTU can be retrieved conveniently using the IP_MTU socket option (e.g. after a EMSGSIZE error occurred). It may change over time. For connectionless sockets with many destinations the new also MTU for a given destination can also be accessed using the error queue (see IP_RECVERR). A new error will be queued for every incoming MTU update.

While MTU discovery is in progress initial packets from datagram sockets may be dropped. Applications using UDP should be aware of this and not take it into account for their packet retransmit strategy.

To bootstrap the path MTU discovery process on unconnected sockets it is possible to start with a big datagram size (up to 64K-headers bytes long) and let it shrink by updates of the path MTU.

To get an initial estimate of the path MTU connect a datagram socket to the destination address using connect(2) and retrieve the MTU by calling getsockopt(2) with the IP_MTU option.

IP_MTU

Retrieve the current known path MTU of the current socket. Only valid when the socket has been connected. Returns an integer. Only valid as a getsockopt(2).

IP_ROUTER_ALERT

Pass all to-be forwarded packets with the IP Router Alert option set to this socket. Only valid for raw sockets. This is useful, for instance, for user space RSVP daemons. The tapped packets are not forwarded by the kernel, it is the users responsibility to send them out again. Socket binding is ignored, such packets are only filtered by protocol. Expects an integer flag.

IP_MULTICAST_TTL

Set or reads the time-to-live value of outgoing multicast packets for this socket. It is very important for multicast packets to set the smallest TTL possible. The default is 1 which means that multicast packets don`t leave the local network unless the user program explicitly requests it. Argument is an integer.

IP_MULTICAST_LOOP

Sets or reads a boolean integer argument whether sent multicast packets should be looped back to the local sockets.

IP_ADD_MEMBERSHIP

Join a multicast group. Argument is a struct ip_mreqn structure.

: struct ip_mreqn { struct in_addr imr_multiaddr; /* IP multicast group address */ struct in_addr imr_address; /* IP address of local interface */ int imr_ifindex; /* interface index */ };

: imr_multiaddr contains the address of the multicast group the application wants to join or leave. It must be a valid multicast address. imr_address is the address of the local interface with which the system should join the multicast group; if it is equal to INADDR_ANY an appropriate interface is chosen by the system. imr_ifindex is the interface index of the interface that should join/leave the imr_multiaddr group, or 0 to indicate any interface.
: For compatibility, the old ip_mreq structure is still supported. It differs from ip_mreqn only by not including the imr_ifindex field. Only valid as a setsockopt(2).
IP_DROP_MEMBERSHIP: Leave a multicast group. Argument is an ip_mreqn or ip_mreq structure similar to IP_ADD_MEMBERSHIP.
IP_MULTICAST_IF: Set the local device for a multicast socket. Argument is an ip_mreqn or ip_mreq structure similar to IP_ADD_MEMBERSHIP.
: When an invalid socket option is passed, ENOPROTOOPT is returned.

SYSCTLS

The IP protocol supports the sysctl interface to configure some global options. The sysctls can be accessed by reading or writing the /proc/sys/net/ipv4/* files or using the sysctl(2) interface.

ip_default_ttl

Set the default time-to-live value of outgoing packets. This can be changed per socket with the IP_TTL option.

ip_forward

Enable IP forwarding with a boolean flag. IP forwarding can be also set on a per interface basis.

ip_dynaddr

Enable dynamic socket address and masquerading entry rewriting on interface address change. This is useful for dialup interface with changing IP addresses. 0 means no rewriting, 1 turns it on and 2 enables verbose mode.

ip_autoconfig

Not documented.

ip_local_port_range

Contains two integers that define the default local port range allocated to sockets. Allocation starts with the first number and ends with the second number. Note that these should not conflict with the ports used by masquerading (although the case is handled). Also arbitary choices may cause problems with some firewall packet filters that make assumptions about the local ports in use. First number should be at least >1024, better >4096 to avoid clashes with well known ports and to minimize firewall problems.

ip_no_pmtu_disc

If enabled, don`t do Path MTU Discovery for TCP sockets by default. Path MTU discovery may fail if misconfigured firewalls (that drop all ICMP packets) or misconfigured interfaces (e.g., a point-to-point link where the both ends don`t agree on the MTU) are on the path. It is better to fix the broken routers on the path than to turn off Path MTU Discovery globally, because not doing it incurs a high cost to the network.

ipfrag_high_thresh, ipfrag_low_thresh

If the amount of queued IP fragments reaches ipfrag_high_thresh, the queue is pruned down to ipfrag_low_thresh. Contains an integer with the number of bytes.

ip_always_defrag

[New with Kernel 2.2.13; in earlier kernel version the feature was controlled at compile time by the CONFIG_IP_ALWAYS_DEFRAG option]

When this boolean frag is enabled (not equal 0) incoming fragments (parts of IP packets that arose when some host between origin and destination decided that the packets were too large and cut them into pieces) will be reassembled (defragmented) before being processed, even if they are about to be forwarded.

Only enable if running either a firewall that is the sole link to your network or a transparent proxy; never ever turn on here for a normal router or host. Otherwise fragmented communication may me disturbed when the fragments would travel over different links. Defragmentation also has a large memory and CPU time cost.

This is automagically turned on when masquerading or transparent proxying are configured.

neigh/*

See arp(7).

IOCTLS

All ioctls described in socket(7) apply to ip.

The ioctls to configure firewalling are documented in ipfw(4) from the ipchains package.

Ioctls to configure generic device parameters are described in netdevice(7).

NOTES

Be very careful with the SO_BROADCAST option - it is not privileged in Linux. It is easy to overload the network with careless broadcasts. For new application protocols it is better to use a multicast group instead of broadcasting. Broadcasting is discouraged.

Some other BSD sockets implementations provide IP_RCVDSTADDR and IP_RECVIF socket options to get the destination address and the interface of received datagrams. Linux has the more general IP_PKTINFO for the same task.

ERRORS

ENOTCONN: The operation is only defined on a connected socket, but the socket wasn`t connected.
EINVAL: Invalid argument passed. For send operations this can be caused by sending to a blackhole route.
EMSGSIZE: Datagram is bigger than an MTU on the path and it cannot be fragmented.
EACCES: The user tried to execute an operation without the necessary permissions. These include: Sending a packet to a broadcast address without having the SO_BROADCAST flag set. Sending a packet via a prohibit route. Modifying firewall settings without CAP_NET_ADMIN or effective user id 0. Binding to a reserved port without the CAP_NET_BIND_SERVICE capacibility or effective user id 0.
EADDRINUSE: Tried to bind to an address already in use.
ENOPROTOOPT and EOPNOTSUPP: Invalid socket option passed.
EPERM: User doesn`t have permission to set high priority, change configuration, or send signals to the requested process or group.
EADDRNOTAVAIL: A non-existent interface was requested or the requested source address was not local.
EAGAIN: Operation on a non-blocking socket would block.
ESOCKTNOSUPPORT: The socket is not configured or an unknown socket type was requested.
EISCONN: connect(2) was called on an already connected socket.
EALREADY: An connection operation on a non-blocking socket is already in progress.
ECONNABORTED: A connection was closed during an accept(2).
EPIPE: The connection was unexpectedly closed or shut down by the other end.
ENOENT: SIOCGSTAMP was called on a socket where no packet arrived.
EHOSTUNREACH: No valid routing table entry matches the destination address. This error can be caused by a ICMP message from a remote router or for the local routing table.
ENODEV: Network device not available or not capable of sending IP.
ENOPKG: A kernel subsystem was not configured.
ENOBUFS, ENOMEM: Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory, but this is not 100% consistent.

Other errors may be generated by the overlaying protocols; see tcp(7), raw(7), udp(7) and socket(7).

VERSIONS

IP_PKTINFO, IP_MTU, IP_MTU_DISCOVER, IP_PKTINFO, IP_RECVERR and IP_ROUTER_ALERT are new options in Linux 2.2. They are also all Linux specific and should not be used in programs intended to be portable.

struct ip_mreqn is new in Linux 2.2. Linux 2.0 only supported ip_mreq.

The sysctls were introduced with Linux 2.2.

COMPATIBILITY

For compatibility with Linux 2.0, the obsolete socket(PF_INET, SOCK_RAW, protocol) syntax is still supported to open a packet(7) socket. This is deprecated and should be replaced by socket(PF_PACKET, SOCK_RAW, protocol) instead. The main difference is the new sockaddr_ll address structure for generic link layer information instead of the old sockaddr_pkt.

BUGS

There are too many inconsistent error values.

The ioctls to configure IP-specific interface options and ARP tables are not described.

Some versions of glibc forget to declare in_pktinfo. Workaround currently is to copy it into your program from this man page.

Receiving the original destination address with MSG_ERRQUEUE in msg_name by recvmsg(2) does not work in some 2.2 kernels.

ipv6

NAME

ipv6, PF_INET6 - Linux IPv6 protocol implementation

SYNOPSIS

#include <sys/socket.h>
#include <netinet/in.h>

tcp6_socket = socket(PF_INET6, SOCK_STREAM, 0);
raw6_socket = socket(PF_INET6, SOCK_RAW, protocol);
udp6_socket = socket(PF_INET6, SOCK_DGRAM, protocol);

DESCRIPTION

Linux 2.2 optionally implements the Internet Protocol, version 6. This man page contains a description of the IPv6 basic API as implemented by the Linux kernel and glibc 2.1. The interface is based on the BSD sockets interface; see socket(7).

The IPv6 API aims to be mostly compatible with the ip(7) v4 API. Only differences are described in this man page.

To bind an AF_INET6 socket to any process the local address should be copied from the in6addr_any variable which has in6_addr type. In static initializations IN6ADDR_ANY_INIT may also be used, which expands to a constant expression. Both of them are in network order.

The IPv6 loopback address (::1) is available in the global in6addr_loopback variable. For initializations IN6ADDR_LOOPBACK_INIT should be used.

IPv4 connections can be handled with the v6 API by using the v4-mapped-on-v6 address type; thus a program only needs only to support this API type to support both protocols. This is handled transparently by the address handling functions in libc.

IPv4 and IPv6 share the local port space. When you get an IPv4 connection or packet to a IPv6 socket its source address will be mapped to v6 and it`ll be mapped to v6.

ADDRESS FORMAT

: struct sockaddr_in6 { u_int16_t sin6_family;/* AF_INET6 */ u_int16_t sin6_port;/* port number */ u_int32_t sin6_flowinfo;/* IPv6 flow information */ struct in6_addr sin6_addr;/* IPv6 address */ u_int32_t sin6_scope_id; /* Scope id (new in 2.4) */ }; struct in6_addr { unsigned char s6_addr[16];/* IPv6 address */ };

sin6_family is always set to AF_INET6; sin6_port is the protocol port (see sin_port in ip(7)); sin6_flowinfo is the IPv6 flow identifier; sin6_addr is the 128bit IPv6 address. sin6_scope_id is an id of depending of on the scope of the address. It is new in Linux 2.4. Linux only supports it for link scope addresses, in that case sin6_scope_id contains the interface index (see netdevice(7))

IPv6 supports several address types: unicast to address a single host, multicast to address a group of hosts, anycast to address the nearest member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to address a IPv4 host, and other reserved address types.

The address notation for IPv6 is a group of 16 2 digit hexadecimal numbers, separated with a `:`. `::` stands for a string of 0 bits. Special addresses are ::1 for loopback and ::FFFF:<IPv4 address> for IPv4-mapped-on-IPv6.

The port space of IPv6 is shared with IPv4.

SOCKET OPTIONS

IPv6 supports some protocol specific socket options that can be set with setsockopt(2) and read with getsockopt(2). The socket option level for IPv6 is IPPROTO_IPV6. A boolean integer flag is zero when it is false, otherwise true.

IPV6_UNICAST_HOPS: Set the unicast hop limit for the socket. Argument is an pointer to an integer. -1 in the value means use the route default, otherwise it should be between 0 and 255.
IPV6_MULTICAST_HOPS: Set the multicast hop limit for the socket. Argument is a pointer to an integer. -1 in the value means use the route default, otherwise it should be between 0 and 255.
IPV6_MULTICAST_IF: Set the device for outgoing multicast packets on the socket. This is only allowed for SOCK_DGRAM and SOCK_RAW socket. The argument is an pointer to an interface index (see netdevice(7)) in an integer.
IPV6_ADDRFORM: Turn an AF_INET6 socket into a socket of a different address family. Only AF_INET is currently supported for that. It is only allowed for IPv6 sockets that are connected and bound to a v4-mapped-on-v6 address. The argument is a pointer to a integer containing AF_INET. This is useful to pass v4-mapped sockets as filedescriptors to programs that don`t know how to deal with the IPv6 API.
IPV6_PKTINFO: Set delivery of the IPV6_PKTINFO control message on incoming datagrams. Only allowed for SOCK_DGRAM or SOCK_RAW sockets. Argument is a pointer to a boolean value in an integer

OpenSource Headlines

Fast Easy Web Hosting

Your Say About Movies

Cigars Review

Man Pages

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

NOTES

EXAMPLES

COMPATIBILITY

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

EXAMPLES

COMPATIBILITY

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

EXAMPLES

COMPATIBILITY

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

EXAMPLES

COMPATIBILITY

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

COMPATIBILITY

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

EXAMPLES

NOTES

COMPATIBILITY

SQL99

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

EXAMPLES

COMPATIBILITY

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

OUTPUTS

NOTES

COMPATIBILITY

NAME

DESCRIPTION

HISTORY

SEE ALSO

TABLES

NAME

SYNOPSIS

DESCRIPTION

AUTHDAEMON AUTHENTICATION MODULE

CONFIGURING AUTHDAEMOND

AUTHENTICATION PROTOCOL

STAND-ALONE AUTHENTICATION MODULES

THE LOGIN PROCESS

THE AUTHENTICATION MODULE

THE APPLICATION PROCESS

LIBRARY FUNCTIONS

A SAMPLE LOGIN PROCESS

A SAMPLE APP PROCESS

INSIDE AN AUTHENTICATION MODULES

STRUCT AUTHSTATICINFO