xfs

title: xfs(5)

text:
# xfs(5)

## NAME
xfs - layout, mount options, and supported file attributes for the XFS filesystem

## DESCRIPTION
An XFS filesystem can reside on a regular disk partition or on a logical volume. An XFS filesystem has up to three parts: a data section, a log section, and a realtime section. Using the default mkfs.xfs(8) options, the realtime section is absent, and the log area is contained within the data section. The log section can be either separate from the data section or contained within it. The filesystem sections are divided into a certain number of blocks, whose size is specified at mkfs.xfs(8) time with the -b option.

The data section contains all the filesystem metadata (inodes, directories, indirect blocks) as well as the user file data for ordinary (non-realtime) files and the log area if the log is internal to the data section. The data section is divided into a number of allocation groups. The number and size of the allocation groups are chosen by mkfs.xfs(8) so that there is normally a small number of equal-sized groups. The number of allocation groups controls the amount of parallelism available in file and block allocation. It should be increased from the default if there is sufficient memory and a lot of allocation activity. The number of allocation groups should not be set very high, since this can cause large amounts of CPU time to be used by the filesystem, especially when the filesystem is nearly full. More allocation groups are added (of the original size) when xfs_growfs(8) is run.

The log section (or area, if it is internal to the data section) is used to store changes to filesystem metadata while the filesystem is running until those changes are made to the data section. It is written sequentially during normal operation and read only during mount. When mounting a filesystem after a crash, the log is read to complete operations that were in progress at the time of the crash.

The realtime section is used to store the data of realtime files. These files had an attribute bit set through xfsctl(3) after file creation, before any data was written to the file. The realtime section is divided into a number of extents of fixed size (specified at mkfs.xfs(8) time). Each file in the realtime section has an extent size that is a multiple of the realtime section extent size.

Each allocation group contains several data structures. The first sector contains the superblock. For allocation groups after the first, the superblock is just a copy and is not updated after mkfs.xfs(8). The next three sectors contain information for block and inode allocation within the allocation group. Also contained within each allocation group are data structures to locate free blocks and inodes; these are located through the header structures.

Each XFS filesystem is labeled with a Universal Unique Identifier (UUID). The UUID is stored in every allocation group header and is used to help distinguish one XFS filesystem from another, therefore you should avoid using dd(1) or other block-by-block copying programs to copy XFS filesystems. If two XFS filesystems on the same machine have the same UUID, xfsdump(8) may become confused when doing incremental and resumed dumps. xfsdump(8) and xfsrestore(8) are recommended for making copies of XFS filesystems. To mount a snapshot of an already-mounted filesystem, you may need to supply the nouuid option to mount (8).

## OPERATIONS
Some functionality specific to the XFS filesystem is accessible to applications through the xfsctl(3) and by-handle (see open_by_handle(3)) interfaces.

## MOUNT OPTIONS
The following XFS-specific mount options may be used when mounting an XFS filesystem. Other generic options may be used as well; refer to the mount(8) manual page for more details.

allocsize=size

Sets the buffered I/O end-of-file preallocation size when doing delayed allocation writeout. Valid values for this option are page size (typically 4KiB) through to 1GiB, inclusive, in power-of-2 increments. The default behavior is for dynamic end-of-file preallocation size, which uses a set of heuristics to optimise the preallocation size based on the current allocation patterns within the file and the access patterns to the file. Specifying a fixed allocsize value turns off the dynamic behavior.

attr2|noattr2

Note: These options have been deprecated as of kernel v5.10; The noattr2 option will be removed no earlier than in September 2025 and attr2 option will be immutable default. The options enable/disable an "opportunistic" improvement to be made in the way inline extended attributes are stored on-disk. When the new form is used for the first time when attr2 is selected (either when setting or removing extended attributes) the on-disk superblock feature bit field will be updated to reflect this format being in use.

The default behavior is determined by the on-disk feature bit indicating that attr2 behavior is active. If either mount option it set, then that becomes the new default used by the filesystem.

CRC enabled filesystems always use the attr2 format, and so will reject the noattr2 mount option if it is set.

dax=value

Set CPU direct access (DAX) behavior for the current filesystem. This mount option accepts the following values: "dax=inode" DAX will be enabled only on regular files with FS_XFLAG_DAX applied.

"dax=never" DAX will not be enabled for any files. FS_XFLAG_DAX will be ignored.

"dax=always" DAX will be enabled for all regular files, regardless of the FS_XFLAG_DAX state.

If no option is used when mounting a filesystem stored on a DAX capable device, dax=inode will be used as default.

For details regarding DAX behavior in kernel, please refer to kernel's documentation at filesystems/dax.txt

discard|nodiscard

Enable/disable the issuing of commands to let the block device reclaim space freed by the filesystem. This is useful for SSD devices, thinly provisioned LUNs and virtual machine images, but may have a performance impact. Note: It is currently recommended that you use the fstrim application to discard unused blocks rather than the discard mount option because the performance impact of this option is quite severe. For this reason, nodiscard is the default.

grpid|bsdgroups|nogrpid|sysvgroups

These options define what group ID a newly created file gets. When grpid is set, it takes the group ID of the directory in which it is created; otherwise it takes the fsgid of the current process, unless the directory has the setgid bit set, in which case it takes the gid from the parent directory, and also gets the setgid bit set if it is a directory itself.

filestreams

Make the data allocator use the filestreams allocation mode across the entire filesystem rather than just on directories configured to use it.

ikeep|noikeep

Note: These options have been deprecated as of kernel v5.10; The noikeep option will be removed no earlier than in September 2025 and ikeep option will be immutable default.

When ikeep is specified, XFS does not delete empty inode clusters and keeps them around on disk. When noikeep is specified, empty inode clusters are returned to the free space pool. noikeep is the default.

inode32|inode64

When inode32 is specified, it indicates that XFS limits inode creation to locations which will not result in inode numbers with more than 32 bits of significance. When inode64 is specified, it indicates that XFS is allowed to create inodes at any location in the filesystem, including those which will result in inode numbers occupying more than 32 bits of significance.

inode32 is provided for backwards compatibility with older systems and applications, since 64 bits inode numbers might cause problems for some applications that cannot handle large inode numbers. If applications are in use which do not handle inode numbers bigger than 32 bits, the inode32 option should be specified.

For kernel v3.7 and later, inode64 is the default.

largeio|nolargeio

If "nolargeio" is specified, the optimal I/O reported in st_blksize by stat(2) will be as small as possible to allow user applications to avoid inefficient read/modify/write I/O. This is typically the page size of the machine, as this is the granularity of the page cache. If "largeio" specified, a filesystem that was created with a "swidth" specified will return the "swidth" value (in bytes) in st_blksize. If the filesystem does not have a "swidth" specified but does specify an "allocsize" then "allocsize" (in bytes) will be returned instead. Otherwise the behavior is the same as if "nolargeio" was specified. nolargeio is the default.

logbufs=value

Set the number of in-memory log buffers. Valid numbers range from 2–8 inclusive. The default value is 8 buffers.

If the memory cost of 8 log buffers is too high on small systems, then it may be reduced at some cost to performance on metadata intensive workloads. The logbsize option below controls the size of each buffer and so is also relevant to this case.

logbsize=value

Set the size of each in-memory log buffer. The size may be specified in bytes, or in kibibytes (KiB) with a "k" suffix. If set manually, logbsize must be one of the specified valid sizes and a multiple of the log stripe unit - configured at mkfs time. Valid sizes for version 1 and version 2 logs are 16384 (value=16k) and 32768 (value=32k). Valid sizes for version 2 logs also include 65536 (value=64k), 131072 (value=128k) and 262144 (value=256k).

The default value for version 1 logs is 32768, while the default value for version 2 logs is max(32768, log_sunit) even if log_sunit does not match one of the valid values above.

logdev=device and rtdev=device

Use an external log (metadata journal) and/or real-time device. An XFS filesystem has up to three parts: a data section, a log section, and a real-time section. The real-time section is optional, and the log section can be separate from the data section or contained within it.

noalign

Data allocations will not be aligned at stripe unit boundaries. This is only relevant to filesystems created with non-zero data alignment parameters (sunit, swidth) by mkfs.

norecovery

The filesystem will be mounted without running log recovery. If the filesystem was not cleanly unmounted, it is likely to be inconsistent when mounted in "norecovery" mode. Some files or directories may not be accessible because of this. Filesystems mounted "norecovery" must be mounted read-only or the mount will fail.

nouuid

Don't check for double mounted file systems using the file system uuid. This is useful to mount LVM snapshot volumes, and often used in combination with "norecovery" for mounting read-only snapshots.

noquota

Forcibly turns off all quota accounting and enforcement within the filesystem.

uquota/usrquota/quota/uqnoenforce/qnoenforce

User disk quota accounting enabled, and limits (optionally) enforced. Refer to xfs_quota(8) for further details.

gquota/grpquota/gqnoenforce

Group disk quota accounting enabled and limits (optionally) enforced. Refer to xfs_quota(8) for further details.

pquota/prjquota/pqnoenforce

Project disk quota accounting enabled and limits (optionally) enforced. Refer to xfs_quota(8) for further details.

sunit=value and swidth=value

Used to specify the stripe unit and width for a RAID device or a stripe volume. "value" must be specified in 512-byte block units. These options are only relevant to filesystems that were created with non-zero data alignment parameters. The sunit and swidth parameters specified must be compatible with the existing filesystem alignment characteristics. In general, that means the only valid changes to sunit are increasing it by a power-of-2 multiple. Valid swidth values are any integer multiple of a valid sunit value.

Typically the only time these mount options are necessary if after an underlying RAID device has had it's geometry modified, such as adding a new disk to a RAID5 lun and reshaping it.

swalloc

Data allocations will be rounded up to stripe width boundaries when the current end of file is being extended and the file size is larger than the stripe width size.

wsync

When specified, all filesystem namespace operations are executed synchronously. This ensures that when the namespace operation (create, unlink, etc) completes, the change to the namespace is on stable storage. This is useful in HA setups where failover must not result in clients seeing inconsistent namespace presentation during or after a failover event.

## REMOVED MOUNT OPTIONS
The following mount options have been removed from the kernel, and will yield mount failures if specified. Mount options are deprecated for a significant period time prior to removal.

Name

Removed

----

-------

delaylog/nodelaylog

v4.0

ihashsize

v4.0

irixsgid

v4.0

osyncisdsync/osyncisosync

v4.0

barrier/nobarrier

v4.19

## FILE ATTRIBUTES
The XFS filesystem supports setting the following file attributes on Linux systems using the chattr(1) utility:

a - append only

A - no atime updates

d - no dump

i - immutable

S - synchronous updates

For descriptions of these attribute flags, please refer to the chattr(1) man page.

## SEE ALSO
chattr(1), xfsctl(3), mount(8), mkfs.xfs(8), xfs_info(8), xfs_admin(8), xfsdump(8), xfsrestore(8).


xinetd.conf

package: xinetd

title: xinetd.conf(5)

text:
# xinetd.conf(5)

## NAME
xinetd.conf - Extended Internet Services Daemon configuration file

## DESCRIPTION
xinetd.conf is the configuration file that determines the services provided by xinetd. Any line whose first non-white-space character is a '#' is considered a comment line. Empty lines are ignored.

The file contains entries of the form:

```
service <service_name>
{
```

```
<attribute> <assign_op> <value> <value> ...
...
```

```
}
```

The assignment operator, assign_op, can be one of '=', '+=', '-='. The majority of attributes support only the simple assignment operator, '='. Attributes whose value is a set of values support all assignment operators. For such attributes, '+=' means adding a value to the set and '-=' means removing a value from the set. A list of these attributes will be given after all the attributes are described.

Each entry defines a service identified by the service_name. The following is a list of available attributes:

id

This attribute is used to uniquely identify a service. This is useful because there exist services that can use different protocols and need to be described with different entries in the configuration file. By default, the service id is the same as the service name.

type

Any combination of the following values may be used:

RPC

if this is an RPC service

INTERNAL

if this is a service provided by xinetd.

TCPMUX/TCPMUXPLUS

if this is a service that will be started according to the RFC 1078 protocol on the TCPMUX well-known port. See the section describing TCPMUX services below.

UNLISTED

if this is a service not listed in a standard system file (like /etc/rpc for RPC services, or /etc/services for non-RPC services).

flags

Any combination of the following flags may be used:

INTERCEPT

Intercept packets or accepted connections in order to verify that they are coming from acceptable locations (internal or multi-threaded services cannot be intercepted).

NORETRY

Avoid retry attempts in case of fork failure.

IDONLY

Accept connections only when the remote end identifies the remote user (i.e. the remote host must run an identification server). This flag applies only to connection-based services. This flag is ineffective if the USERID log option is not used.

NAMEINARGS

This will cause the first argument in "server_args" to be argv[0] when executing the server, as specified in "server". This allows you to use tcpd by putting tcpd in "server" and the name of the server in "server_args" like in normal inetd.

NODELAY

If the service is a tcp service and the NODELAY flag is set, then the TCP_NODELAY flag will be set on the socket. If the service is not a tcp service, this option has no effect.

KEEPALIVE

If the service is a tcp service and the KEEPALIVE flag is set, then the SO_KEEPALIVE socket flag will be set on the socket. If the service is not a tcp service, this option has no effect.

NOLIBWRAP

This disables internal calling of the tcpwrap library to determine access to the service. This may be needed in order to use libwrap functionality not available to long-running processes such as xinetd; in this case, the tcpd program can be called explicitly (see also the NAMEINARGS flag). For RPC services using TCP transport, this flag is automatically turned on, because xinetd cannot get remote host address information for the rpc port.

SENSOR

This replaces the service with a sensor that detects accesses to the specified port. NOTE: It will NOT detect stealth scans. This flag should be used only on services that you know you don't need. When an access is made to this service's port, the IP Address is added to a global no_access list. This causes all subsequent accesses from the originating IP address to be denied access until the deny_time setting expires. The amount of time spent on this list is configurable as the deny_time attribute. The SENSOR flag will also cause xinetd to consider the server attribute to be INTERNAL no matter what is typed on the same line. Another important thing to remember is that if the socket_type is set to stream, then the wait attribute should be set to no.

IPv4

Sets the service to be an IPv4 service (AF_INET).

IPv6

Sets the service to be an IPv6 service (AF_INET6), if IPv6 is available on the system.

LABELED

The LABELED flag will tell xinetd to change the child processes SE Linux context to match that of the incoming connection as it starts the service. This only works for external tcp non-waiting servers and is an error if applied to an internal, udp, or tcp-wait server.

REUSE

The REUSE flag is deprecated. All services now implicitly use the REUSE flag.

disable

This is boolean "yes" or "no". This will result in the service being disabled and not starting. See the DISABLE flag description.

socket_type

Possible values for this attribute include:

stream

stream-based service

dgram

datagram-based service

raw

service that requires direct access to IP

seqpacket

service that requires reliable sequential datagram transmission

protocol

determines the protocol that is employed by the service. The protocol must exist in /etc/protocols. If this attribute is not defined, the default protocol employed by the service will be used.

wait

This attribute determines if the service is single-threaded or multi-threaded and whether or not xinetd accepts the connection or the server program accepts the connection. If its value is yes, the service is single-threaded; this means that xinetd will start the server and then it will stop handling requests for the service until the server dies and that the server software will accept the connection. If the attribute value is no, the service is multi-threaded and xinetd will keep handling new service requests and xinetd will accept the connection. It should be noted that udp/dgram services normally expect the value to be yes since udp is not connection oriented, while tcp/stream servers normally expect the value to be no.

user

determines the uid for the server process. The user attribute can either be numeric or a name. If a name is given (recommended), the user name must exist in /etc/passwd. This attribute is ineffective if the effective user ID of xinetd is not super-user.

group

determines the gid for the server process. The group attribute can either be numeric or a name. If a name is given (recommended), the group name must exist in /etc/group. If a group is not specified, the group of user will be used (from /etc/passwd). This attribute is ineffective if the effective user ID of xinetd is not super-user and if the groups attribute is not set to 'yes'.

instances

determines the number of servers that can be simultaneously active for a service (the default is no limit). The value of this attribute can be either a number or UNLIMITED which means that there is no limit.

nice

determines the server priority. Its value is a (possibly negative) number; check nice(3) for more information.

server

determines the program to execute for this service.

server_args

determines the arguments passed to the server. In contrast to inetd, the server name should not be included in server_args.

libwrap

overrides the service name passed to libwrap (which defaults to the server name, the first server_args component with NAMEINARGS, the id for internal services and the service name for redirected services). This attribute is only valid if xinetd has been configured with the libwrap option.

only_from

determines the remote hosts to which the particular service is available. Its value is a list of IP addresses which can be specified in any combination of the following ways:

a)

a numeric address in the form of %d.%d.%d.%d. If the rightmost components are 0, they are treated as wildcards (for example, 128.138.12.0 matches all hosts on the 128.138.12 subnet). 0.0.0.0 matches all Internet addresses. IPv6 hosts may be specified in the form of abcd:ef01::2345:6789. The rightmost rule for IPv4 addresses does not apply to IPv6 addresses.

b)

a factorized address in the form of %d.%d.%d.{%d,%d,...}. There is no need for all 4 components (i.e. %d.%d.{%d,%d,...%d} is also ok). However, the factorized part must be at the end of the address. This form does not work for IPv6 hosts.

c)

a network name (from /etc/networks). This form does not work for IPv6 hosts.

d)

a host name. When a connection is made to xinetd, a reverse lookup is performed, and the canonical name returned is compared to the specified host name. You may also use domain names in the form of .domain.com. If the reverse lookup of the client's IP is within .domain.com, a match occurs.

e)

an ip address/netmask range in the form of 1.2.3.4/32. IPv6 address/netmask ranges in the form of 1234::/46 are also valid.

Specifying this attribute without a value makes the service available to nobody.

no_access

determines the remote hosts to which the particular service is unavailable. Its value can be specified in the same way as the value of the only_from attribute. These two attributes determine the location access control enforced by xinetd. If none of the two is specified for a service, the service is available to anyone. If both are specified for a service, the one that is the better match for the address of the remote host determines if the service is available to that host (for example, if the only_from list contains 128.138.209.0 and the no_access list contains 128.138.209.10 then the host with the address 128.138.209.10 can not access the service).

access_times

determines the time intervals when the service is available. An interval has the form hour:min-hour:min (connections will be accepted at the bounds of an interval). Hours can range from 0 to 23 and minutes from 0 to 59.

log_type

determines where the service log output is sent. There are two formats:

SYSLOG syslog_facility [syslog_level]

The log output is sent to syslog at the specified facility. Possible facility names include: daemon, auth, authpriv, user, mail, lpr, news, uucp, ftp local0-7. Possible level names include: emerg, alert, crit, err, warning, notice, info, debug. If a level is not present, the messages will be recorded at the info level.

FILE file [soft_limit [hard_limit]]

The log output is appended to file which will be created if it does not exist. Two limits on the size of the log file can be optionally specified. The first limit is a soft one; xinetd will log a message the first time this limit is exceeded (if xinetd logs to syslog, the message will be sent at the alert priority level). The second limit is a hard limit; xinetd will stop logging for the affected service (if the log file is a common log file, then more than one service may be affected) and will log a message about this (if xinetd logs to syslog, the message will be sent at the alert priority level). If a hard limit is not specified, it defaults to the soft limit increased by 1% but the extra size must be within the parameters LOG_EXTRA_MIN and LOG_EXTRA_MAX which default to 5K and 20K respectively (these constants are defined in xconfig.h).

log_on_success

determines what information is logged when a server is started and when that server exits (the service id is always included in the log entry). Any combination of the following values may be specified:

PID

logs the server process id (if the service is implemented by xinetd without forking another process the logged process id will be 0)

HOST

logs the remote host address

USERID

logs the user id of the remote user using the RFC 1413 identification protocol. This option is available only for multi-threaded stream services.

EXIT

logs the fact that a server exited along with the exit status or the termination signal (the process id is also logged if the PID option is used)

DURATION

logs the duration of a service session

TRAFFIC

logs the total bytes in and out for a redirected service.

log_on_failure

determines what information is logged when a server cannot be started (either because of a lack of resources or because of access control restrictions). The service id is always included in the log entry along with the reason for failure. Any combination of the following values may be specified:

HOST

logs the remote host address.

USERID

logs the user id of the remote user using the RFC 1413 identification protocol. This option is available only for multi-threaded stream services.

ATTEMPT

logs the fact that a failed attempt was made (this option is implied by all others).

rpc_version

determines the RPC version for a RPC service. The version can be a single number or a range in the form number-number.

rpc_number

determines the number for an UNLISTED RPC service (this attribute is ignored if the service is not unlisted).

env

The value of this attribute is a list of strings of the form 'name=value'. These strings will be added to the environment before starting a server (therefore the server's environment will include xinetd's environment plus the specified strings).

passenv

The value of this attribute is a list of environment variables from xinetd's environment that will be passed to the server. An empty list implies passing no variables to the server except for those explicitly defined using the env attribute. (notice that you can use this attribute in conjunction with the env attribute to specify exactly what environment will be passed to the server).

port

determines the service port. If this attribute is specified for a service listed in /etc/services, it must be equal to the port number listed in that file.

redirect

Allows a tcp service to be redirected to another host. When xinetd receives a tcp connection on this port it spawns a process that establishes a connection to the host and port number specified, and forwards all data between the two hosts. This option is useful when your internal machines are not visible to the outside world. Syntax is: redirect = (ip address) (port). You can also use a hostname instead of the IP address in this field. The hostname lookup is performed only once, when xinetd is started, and the first IP address returned is the one that is used until xinetd is restarted. The "server" attribute is not required when this option is specified. If the "server" attribute is specified, this attribute takes priority.

bind

Allows a service to be bound to a specific interface on the machine. This means you can have a telnet server listening on a local, secured interface, and not on the external interface. Or one port on one interface can do something, while the same port on a different interface can do something completely different. Syntax: bind = (ip address of interface).

interface

Synonym for bind.

banner

Takes the name of a file to be splatted at the remote host when a connection to that service is established. This banner is printed regardless of access control. It should *always* be printed when a connection has been made. xinetd outputs the file as-is, so you must ensure the file is correctly formatted for the service's protocol. In paticular, if the protocol requires CR-LF pairs for line termination, you must supply them.

banner_success

Takes the name of a file to be splatted at the remote host when a connection to that service is granted. This banner is printed as soon as access is granted for the service. xinetd outputs the file as-is, so you must ensure the file is correctly formatted for the service's protocol. In paticular, if the protocol requires CR-LF pairs for line termination, you must supply them.

banner_fail

Takes the name of a file to be splatted at the remote host when a connection to that service is denied. This banner is printed immediately upon denial of access. This is useful for informing your users that they are doing something bad and they shouldn't be doing it anymore. xinetd outputs the file as-is, so you must ensure the file is correctly formatted for the service's protocol. In paticular, if the protocol requires CR-LF pairs for line termination, you must supply them.

per_source

Takes an integer or "UNLIMITED" as an argument. This specifies the maximum instances of this service per source IP address. This can also be specified in the defaults section.

cps

Limits the rate of incoming connections. Takes two arguments. The first argument is the number of connections per second to handle. If the rate of incoming connections is higher than this, the service will be temporarily disabled. The second argument is the number of seconds to wait before re-enabling the service after it has been disabled. The default for this setting is 50 incoming connections and the interval is 10 seconds.

max_load

Takes a floating point value as the load at which the service will stop accepting connections. For example: 2 or 2.5. The service will stop accepting connections at this load. This is the one minute load average. This is an OS dependent feature, and currently only Linux, Solaris, and FreeBSD are supported for this. This feature is only avaliable if xinetd was configured with the -with-loadavg option.

groups

Takes either "yes" or "no". If the groups attribute is set to "yes", then the server is executed with access to the groups that the server's effective UID has access to. Alternatively, if the group attribute is set, the server is executed with access to the groups specified. If the groups attribute is set to "no", then the server runs with no supplementary groups. This attribute must be set to "yes" for many BSD systems. This attribute can be set in the defaults section as well.

mdns

Takes either "yes" or "no". On systems that support mdns registration of services (currently only Mac OS X), this will enable or disable registration of the service. This defaults to "yes".

umask

Sets the inherited umask for the service. Expects an octal value. This option may be set in the "defaults" section to set a umask for all services. xinetd sets its own umask to the previous umask OR'd with 022. This is the umask that will be inherited by all child processes if the umask option is not used.

enabled

Takes a list of service ID's to enable. This will enable only the services listed as arguments to this attribute; the rest will be disabled. If you have 2 ftp services, you will need to list both of their ID's and not just ftp. (ftp is the service name, not the ID. It might accidentally be the ID, but you better check.) Note that the service "disable" attribute and "DISABLE" flag can prevent a service from being enabled despite being listed in this attribute.

include

Takes a filename in the form of "include /etc/xinetd/service". The file is then parsed as a new configuration file. It is not the same thing as pasting the file into xinetd.conf where the include directive is given. The included file must be in the same form as xinetd.conf. This may not be specified from within a service. It must be specified outside a service declaration.

includedir

Takes a directory name in the form of "includedir /etc/xinetd.d". Every file inside that directory, excluding files with names containing a dot ('.') or ending with a tilde ('~'), will be parsed as xinetd configuration files. The files will be parsed in alphabetical order according to the C locale. This allows you to specify services one per file within a directory. The includedir directive may not be specified from within a service declaration.

rlimit_as

Sets the Address Space resource limit for the service. One parameter is required, which is either a positive integer representing the number of bytes to set the limit to (K or M may be used to specify kilobytes/megabytes) or "UNLIMITED". Due to the way Linux's libc malloc is implemented, it is more useful to set this limit than rlimit_data, rlimit_rss and rlimit_stack. This resource limit is only implemented on Linux systems.

rlimit_cpu

Sets the maximum number of CPU seconds that the service may use. One parameter is required, which is either a positive integer representing the number of CPU seconds limit to, or "UNLIMITED".

rlimit_data

Sets the maximum data size resource limit for the service. One parameter is required, which is either a positive integer representing the number of bytes or "UNLIMITED".

rlimit_rss

Sets the maximum resident set size limit for the service. Setting this value low will make the process a likely candidate for swapping out to disk when memory is low. One parameter is required, which is either a positive integer representing the number of bytes or "UNLIMITED".

rlimit_stack

Set the maximum stack size limit for the service. One parameter is required, which is either a positive integer representing the number of bytes or "UNLIMITED".

deny_time

Sets the time span that access to all services on all IP addresses are denied to someone that sets off the SENSOR. The unit of time is in minutes. Valid options are: FOREVER, NEVER, and a numeric value. FOREVER causes the IP address not to be purged until xinetd is restarted. NEVER has the effect of just logging the offending IP address. A typical time value would be 60 minutes. This should stop most DOS attacks while allowing IP addresses that come from a pool to be recycled for legitimate purposes. This option must be used in conjunction with the SENSOR flag.

You don't need to specify all of the above attributes for each service. The necessary attributes for a service are:

socket_type

user

(non-internal services only)

server

(non-internal services only)

wait

protocol

(RPC and unlisted services only)

rpc_version

(RPC services only)

rpc_number

(unlisted RPC services only)

port

(unlisted non-RPC services only)

The following attributes support all assignment operators:

only_from

no_access

log_on_success

log_on_failure

passenv

env

(does not support the '-=' operator)

These attributes can also appear more than once in a service entry. The remaining attributes support only the '=' operator and can appear at most once in a service entry.

The configuration file may also contain a single defaults entry that has the form

```
defaults
{
```

```
<attribute> = <value> <value> ...
...
```

```
}
```

This entry provides default attribute values for service entries that don't specify those attributes. Possible default attributes:

log_type

(cumulative effect)

bind

per_source

umask

log_on_success

(cumulative effect)

log_on_failure

(cumulative effect)

only_from

(cumulative effect)

no_access

(cumulative effect)

passenv

(cumulative effect)

instances

disabled

(cumulative effect)

enabled

(cumulative effect)

banner

banner_success

banner_fail

per_source

groups

cps

max_load

Attributes with a cumulative effect can be specified multiple times with the values specified each time accumulating (i.e. '=' does the same thing as '+='). With the exception of disabled they all have the same meaning as if they were specified in a service entry. disabled determines services that are disabled even if they have entries in the configuration file. This allows for quick reconfiguration by specifying disabled services with the disabled attribute instead of commenting them out. The value of this attribute is a list of space separated service ids. enabled has the same properties as disabled. The difference being that enabled is a list of which services are to be enabled. If enabled is specified, only the services specified are available. If enabled is not specified, all services are assumed to be enabled, except those listed in disabled.

## INTERNAL SERVICES
xinetd provides the following services internally (both stream and datagram based): echo, time, daytime, chargen, and discard. These services are under the same access restrictions as all other services except for the ones that don't require xinetd to fork another process for them. Those ones (time, daytime, and the datagram-based echo, chargen, and discard) have no limitation in the number of instances.

## TCPMUX Services
xinetd supports TCPMUX services that conform to RFC 1078. These services may not have a well-known port associated with them, and can be accessed via the TCPMUX well-known port.

For each service that is to be accessed via TCPMUX, a service entry in /etc/xinetd.conf or in a configuration file in an includedir directory must exist.

The service_name field (as defined above for each service in any xinetd configuration file) must be identical to the string that is passed (according to RFC 1078 protocol) to xinetd when the remote service requestor first makes the connection on the TCPMUX well-known port. Private protocols should use a service name that has a high probability of being unique. One way is to prepend the service name with some form of organization ID.

The type field can be either TCPMUX or TCPMUXPLUS. If the type is TCPMUXPLUS, xinetd will handle the initial protocol handshake (as defined in RFC 1078) with the calling process before initiating the service. If the type is TCPMUX, the server that is started is responsible for performing the handshake.

The type field should also include UNLISTED if the service is not listed in a standard system file (like /etc/rpc for RPC services, or /etc/services for non-RPC services).

The socket_type for these services must be stream, and the protocol must be tcp.

Following is a sample TCPMUX service configuration:

```
service myorg_server
{
```

disable

```
= no
```

type

```
= TCPMUX
```

socket_type

```
= stream
```

protocol

```
= tcp
```

wait

```
= no
```

user

```
= root
```

server

```
= /usr/etc/my_server_exec
```

```
}
```

Besides a service entry for each service that can be accessed via the TCPMUX well-known port, a service entry for TCPMUX itself must also be included in the xinetd configuration. Consider the following sample:

```
service tcpmux
{
```

type

```
= INTERNAL
```

id

```
= tcpmux
```

socket_type

```
= stream
```

protocol

```
= tcp
```

user

```
= root
```

wait

```
= no
```

```
}
```

## NOTES
1.

The following service attributes cannot be changed on reconfiguration: socket_type, wait, protocol, type.

2.

When the attributes only_from and no_access are not specified for a service (either directly or via defaults) the address check is considered successful (i.e. access will not be denied).

3.

The address check is based on the IP address of the remote host and not on its domain address. We do this so that we can avoid remote name lookups which may take a long time (since xinetd is single-threaded, a name lookup will prevent the daemon from accepting any other requests until the lookup is resolved). The down side of this scheme is that if the IP address of a remote host changes, then access to that host may be denied until xinetd is reconfigured. Whether access is actually denied or not will depend on whether the new host IP address is among those allowed access. For example, if the IP address of a host changes from 1.2.3.4 to 1.2.3.5 and only_from is specified as 1.2.3.0 then access will not be denied.

4.

If the USERID log option is specified and the remote host either does not run an identification server or the server sends back a bad reply, access will not be denied unless the IDONLY service flag is used.

5.

Interception works by forking a process which acts as a filter between the remote host(s) and the local server. This obviously has a performance impact so it is up to you to make the compromise between security and performance for each service. The following tables show the overhead of interception. The first table shows the time overhead-per-datagram for a UDP-based service using various datagram sizes. For TCP-based services we measured the bandwidth reduction because of interception while sending a certain amount of data from client to server (the time overhead should the same as for UDP-based services but it is "paid" only by the first packet of a continuous data transmission). The amount of data is given in the table as system_callsxdata_sent_per_call, i.e. each send(2) system call transferred so many bytes of data. The bandwidth reduction is given in terms of bytes per second and as a percentage of the bandwidth when interception is not performed. All measurements were done on a SparcStation IPC running SunOS 4.1.

Datagram size (bytes)

Latency (msec)

---------------------

--------------

64

1.19

256

1.51

1024

1.51

4096

3.58

Bytes sent

Bandwidth reduction

----------

-------------------

10000x64

941 (1.2%)

10000x256

4,231 (1.8%)

10000x1024

319,300 (39.5%)

10000x4096

824,461 (62.1%)

## EXAMPLE

```
#
# Sample configuration file for xinetd
#
defaults
{
```

log_type

```
= FILE /var/log/servicelog
```

log_on_success

```
= PID
```

log_on_failure

```
= HOST
```

only_from

```
= 128.138.193.0 128.138.204.0
```

only_from

```
= 128.138.252.1
```

instances

```
= 10
```

disabled

```
= rstatd
```

```
}
#
# Note 1: the protocol attribute is not required
# Note 2: the instances attribute overrides the default
#
service login
{
```

socket_type

```
= stream
```

protocol

```
= tcp
```

wait

```
= no
```

user

```
= root
```

server

```
= /usr/etc/in.rlogind
```

instances

```
= UNLIMITED
```

```
}
#
# Note 1: the instances attribute overrides the default
# Note 2: the log_on_success flags are augmented
#
service shell
{
```

socket_type

```
= stream
```

wait

```
= no
```

user

```
= root
```

instances

```
= UNLIMITED
```

server

```
= /usr/etc/in.rshd
```

log_on_success

```
+= HOST
```

```
}
service ftp
{
```

socket_type

```
= stream
```

wait

```
= no
```

nice

```
= 10
```

user

```
= root
```

server

```
= /usr/etc/in.ftpd
```

server_args

```
= -l
```

instances

```
= 4
```

log_on_success

```
+= DURATION HOST USERID
```

access_times

```
= 2:00-9:00 12:00-24:00
```

```
}
# Limit telnet sessions to 8 Mbytes of memory and a total
# 20 CPU seconds for child processes.
service telnet
{
```

socket_type

```
= stream
```

wait

```
= no
```

nice

```
= 10
```

user

```
= root
```

server

```
= /usr/etc/in.telnetd
```

rlimit_as

```
= 8M
```

rlimit_cpu

```
= 20
```

```
}
#
# This entry and the next one specify internal services. Since
# this is the same service using a different socket type, the
# id attribute is used to uniquely identify each entry
#
service echo
{
```

id

```
= echo-stream
```

type

```
= INTERNAL
```

socket_type

```
= stream
```

user

```
= root
```

wait

```
= no
```

```
}
service echo
{
```

id

```
= echo-dgram
```

type

```
= INTERNAL
```

socket_type

```
= dgram
```

user

```
= root
```

wait

```
= no
```

```
}
#
# Sample RPC service
#
service rstatd
{
```

type

```
= RPC
```

socket_type

```
= dgram
```

protocol

```
= udp
```

server

```
= /usr/etc/rpc.rstatd
```

wait

```
= yes
```

user

```
= root
```

rpc_version

```
= 2-4
```

env

```
= LD_LIBRARY_PATH=/etc/securelib
```

```
}
#
# Sample unlisted service
#
service unlisted
{
```

type

```
= UNLISTED
```

socket_type

```
= stream
```

protocol

```
= tcp
```

wait

```
= no
```

server

```
= /home/user/some_server
```

port

```
= 20020
```

```
}
```

```

```

## SEE ALSO
xinetd(1L),

xinetd.log(5)

Postel J., Echo Protocol, RFC 862, May 1983

Postel J., Discard Protocol, RFC 863, May 1983

Postel J., Character Generator Protocol, RFC 864, May 1983

Postel J., Daytime Protocol, RFC 867, May 1983

Postel J., Harrenstien K., Time Protocol, RFC 868, May 1983

M. Lottor, TCP Port Service Multiplexer (TCPMUX), RFC 1078 Nov 1988

StJohns M., Identification Protocol, RFC 1413, February 1993

## BUGS
If the INTERCEPT flag is not used, access control on the address of the remote host is not performed when wait is yes and socket_type is stream.

The NOLIBWRAP flag is automatically turned on for RPC services whose socket_type is stream because xinetd cannot determine the address of the remote host.

If the INTERCEPT flag is not used, access control on the address of the remote host for services where wait is yes and socket_type is dgram is performed only on the first packet. The server may then accept packets from hosts not in the access control list. This can happen with RPC services.

There is no way to put a SPACE in an environment variable.

When wait is yes and socket_type is stream, the socket passed to the server can only accept connections.

The INTERCEPT flag is not supported for internal services or multi-threaded services.

branch: sisyphus


xinetd.log

title: xinetd.log(5)

summary: xinetd service log format

text:
# xinetd.log(5)

## NAME
xinetd.log - xinetd service log format

## DESCRIPTION
A service configuration may specify various degrees of logging when attempts are made to access the service. When logging for a service is enabled, xinetd will generate one-line log entries which have the following format (all entries have a timestamp as a prefix):

entry: service-id data

The data depends on the entry. Possible entry types include:

START

generated when a server is started

EXIT

generated when a server exits

FAIL

generated when it is not possible to start a server

USERID

generated if the USERID log option is used.

NOID

generated if the USERID log option is used, and the IDONLY service flag is used, and the remote end does not identify who is trying to access the service.

In the following, the information enclosed in brackets appears if the appropriate log option is used.

A START entry has the format:

START: service-id [pid=%d] [from=%d.%d.%d.%d]

An EXIT entry has the format:

EXIT: service-id [type=%d] [pid=%d] [duration=%d(sec)]

type can be either status or signal. The number is either the exit status or the signal that caused process termination.

A FAIL entry has the format:

FAIL: service-id reason [from=%d.%d.%d.%d]

Possible reasons are:

fork

a certain number of consecutive fork attempts failed (this number is a configurable parameter)

time

the time check failed

address

the address check failed

service_limit

the allowed number of server instances for this service would be exceeded

process_limit

a limit on the number of forked processes was specified and it would be exceeded

A DATA entry has the format:

DATA: service-id data

The data logged depends on the service.

login

remote_user=%s local_user=%s tty=%s

exec

remote_user=%s verify=status command=%s

Possible status values:

ok

the password was correct

failed

the password was incorrect

baduser

no such user

shell

remote_user=%s local_user=%s command=%s

finger

received string or EMPTY-LINE

A USERID entry has the format:

USERID: service-id text

The text is the response of the identification daemon at the remote end excluding the port numbers (which are included in the response).

A NOID entry has the format:

NOID: service-id IP-address reason

## SEE ALSO
xinetd(1L), xinetd.conf(5)


title: l2tp-secrets(5)

summary: L2TPD secrets file

text:
# l2tp-secrets(5)

## NAME
l2tp-secrets - L2TPD secrets file

## DESCRIPTION
The l2tp-secrets file contains challenge-response authentication information for xl2tpd, the implementation of l2tp protocol. The format of the file is derived from the pap and chap secrets file format used in pppd.

The secrets file is composed of zero or more lines with 3 fields each. Each line represents an authentication secret. The 3 fields represent our hostname, the remote hostname and the secret used in the authentication process.

The first field is for our hostname, a "*" may be used as a wildcard.

The second field is for the remote system's hostname. Again, a "*" may be used as a wildcard.

The third field is the secret used if the previous two fields match the hostnames of the systems involved. The secret should, ideally, be at 16 characters long (the length of an MD5 digest output), and should probably be longer to ensure sufficient security. There is no minimum length requirement, however.

## FILES
/etc/xl2tpd/xl2tpd.conf

/etc/xl2tpd/l2tp-secrets

/var/run/xl2tpd/l2tp-control

## BUGS
Please send bugs and comment to xl2tpd@lists.xelerance.com

## SEE ALSO
xl2tpd(8), xl2tpd.conf(5)

## AUTHORS
Michael Richardson <mcr@xelerance.com> Paul Wouters <paul@xelerance.com>

Patched contributed by:

Jacco de Leeuw <jacco2@dds.nl>

Cedric Schieli <cschieli@gmail.com>

Previous development was hosted at sourceforge (http://www.sourceforge.net/projects/l2tpd) by:

Scott Balmos <sbalmos@iglou.com>

David Stipp <dstipp@one.net>

Jeff McAdams <jeffm@iglou.com>

Based off of l2tpd version 0.60

Copyright (C)1998 Adtran, Inc.

Mark Spencer <markster@marko.net>


title: xl2tpd.conf(5)

summary: L2TPD configuration file

text:
# xl2tpd.conf(5)

## NAME
xl2tpd.conf - L2TPD configuration file

## DESCRIPTION
The xl2tpd.conf file contains configuration information for xl2tpd, the free implementation of l2tp protocol.

The configuration file is composed of sections and parameters. Each section has a given name which will be used when using the configuration FIFO (normally /var/run/xl2tpd/l2tp-control). See xl2tpd.8 for more details.

The specific given name default will specify parameters applicable for all the following sections.

## GLOBAL SECTION
auth file

Specify where to find the authentication file used to authenticate l2tp tunnels. The default is /etc/xl2tpd/l2tp-secrets.

ipsec saref

Use IPsec Security Association tracking. When this is enabled, packets received by xl2tpd should have two extra fields (refme and refhim) which allows tracking of multiple clients using the same internal NATed IP address, and allows tracking of multiple clients behind the same NAT router. This needs to be supported by the kernel. Currently, this only works with Openswan KLIPS in "mast" mode. (see http://www.openswan.org/) Set this to yes and the system will provide proper SAref values in the recvmsg() calls.

Values can be 'yes' or 'no'. The default is 'no'.

saref refinfo

When using IPsec Security Association trackinng, a new setsockopt is used. Since this is not (yet?) an official Linux kernel option, we got bumped. Openswan upto 2.6.35 for linux kernels up to 2.6.35 used a saref num of 22. Linux 3.6.36+ uses 22 for IP_NODEFRAG. We moved our IP_IPSEC_REFINFO to 30. If not set, the default is to use 30. For older SAref patched kernels, use 22.

listen-addr

The IP address of the interface on which the daemon listens. By default, it listens on INADDR_ANY (0.0.0.0), meaning it listens on all interfaces.

port

Specify which UDP port xl2tpd should use. The default is 1701.

access control

If set to 'yes', the xl2tpd process will only accept connections from peers addresses specified in the following sections. The default is 'no'.

debug avp

Set this to 'yes' to enable syslog output of L2TP AVP debugging information.

debug network

Set this to 'yes' to enable syslog output of network debugging information.

debug packet

Set this to 'yes' to enable printing of L2TP packet debugging information. Note: Output goes to STDOUT, so use this only in conjunction with the -D command line option.

debug state

Set this to 'yes' to enable syslog output of FSM debugging information.

debug tunnel

Set this to 'yes' to enable syslog output of tunnel debugging information.

max retries

Specify how many retries before a tunnel is closed. If there is no tunnel, then stop re-transmitting. The default is 5.

## LNS SECTION
exclusive

If set to 'yes', only one control tunnel will be allowed to be built between 2 peers.

(no) ip range

Specify the range of IP addresses the LNS will assign to the connecting LAC PPP tunnels. Multiple ranges can be defined. Using the 'no' statement disallows the use of that particular range. Ranges are defined using the format IP - IP (example: 1.1.1.1 - 1.1.1.10). Note that either at least one ip range option must be given, or you must set assign ip to no.

assign ip

Set this to 'no' if xl2tpd should not assign IP addresses out of the pool defined with the ip range option. This can be useful if you have some other means to assign IP addresses, e. g. a pppd that supports RADIUS AAA.

(no) lac

Specify the IP addresses of LAC's which are allowed to connect to xl2tpd acting as a LNS. The format is the same as the ip range option.

hidden bit

If set to 'yes', xl2tpd will use the AVP hiding feature of L2TP. To get more information about hidden AVP's and AVP in general, refer to rfc2661 (add URL?)

local ip

Use the following IP as xl2tpd's own IP address.

local ip range

Specify the range of addresses the LNS will assign as the local address to connecting LAC PPP tunnels. This option is mutually exclusive with the local ip option and is useful in cases where it is desirable to have a unique IP address for each tunnel. Specify the range value exactly like the ip range option. Note that the assign ip option has no effect on this option.

length bit

If set to 'yes', the length bit present in the l2tp packet payload will be used.

(refuse | require) chap

Will require or refuse the remote peer to get authenticated via CHAP for the ppp authentication.

(refuse | require) pap

Will require or refuse the remote peer to get authenticated via PAP for the ppp authentication.

(refuse | require) authentication

Will require or refuse the remote peer to authenticate itself.

unix authentication

If set to 'yes', /etc/passwd will be used for remote peer ppp authentication.

hostname

Will report this as the xl2tpd hostname in negotiation.

ppp debug

This will enable the debug for pppd.

pass peer

Pass the peer's IP address to pppd as ipparam. Enabled by default.

pppoptfile

Specify the path for a file which contains pppd configuration parameters to be used.

call rws

This option is deprecated and no longer functions. It used to be used to define the flow control window size for individual L2TP calls or sessions. The L2TP standard (RFC2661) no longer defines flow control or window sizes on calls or sessions.

tunnel rws

This defines the window size of the control channel. The window size is defined as the number of outstanding unacknowledged packets, not as a number of bytes.

flow bits

If set to 'yes', sequence numbers will be included in the communication. The feature to use sequence numbers in sessions is currently broken and does not function.

challenge

If set to 'yes', use challenge authentication to authenticate peer.

rx bps

If set, the receive bandwidth maximum will be set to this value

tx bps

If set, the transmit bandwidth maximum will be set to this value

## LAC SECTION
The following are LAC specific configuration flags. Most of those described in the LNS section may be used in a LAC context, where it makes common sense (essentially l2tp protocols tuning flags and authentication / ppp related ones).

lns

Set the dns name or ip address of the LNS to connect to.

autodial

If set to 'yes', xl2tpd will automatically dial the LAC during startup.

redial

If set to 'yes', xl2tpd will attempt to redial if the call get disconnected. Note that, if enabled, xl2tpd will keep passwords in memory: a potential security risk.

redial timeout

Wait X seconds before redial. The redial option must be set to yes to use this option. Defaults to 30 seconds.

max redials

Will give up redial tries after X attempts.

## FILES
/etc/xl2tpd/xl2tpd.conf

Configuration file of xl2tpd, used by default.

/etc/xl2tpd/l2tp-secrets

Secrets file, used by default.

/var/run/xl2tpd/l2tp-control

Control file, used by default.

## BUGS
Please use the github project page https://github.com/xelerance/xl2tpd to send bugreports, issues and any other feedback

## SEE ALSO
xl2tpd(8), xl2tpd-control(8), pppd(8)

## COPYLEFT
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 program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see the file LICENSE); if not, see https://www.gnu.org/licenses/, or contact Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

## CONTRIBUTORS
Alexander Dorokhov <alex.dorokhov@gmail.com>

Alexander Naumov <alexander_naumov@opensuse.org>

## AUTHORS
Forked from l2tpd by Xelerance: https://github.com/xelerance/xl2tpd

Michael Richardson <mcr@xelerance.com>

Paul Wouters <paul@xelerance.com>

Samir Hussain <shussain@xelerance.com>

Previous development was hosted at sourceforge (http://www.sourceforge.net/projects/l2tpd) by:

Scott Balmos <sbalmos@iglou.com>

David Stipp <dstipp@one.net>

Jeff McAdams <jeffm@iglou.com>

Based off of l2tpd version 0.61. Many thanks to Jacco de Leeuw <jacco2@dds.nl> for maintaining l2tpd.

Copyright (C)1998 Adtran, Inc.

Mark Spencer <markster@marko.net>


xliguide

package: xli

title: xliguide(5)

text:
# xliguide(5)

## Guide to writing image loaders for xli
This is a introduction on how an image load routine should be written, and what resources are available for use by the writer.

## Include files
The include file xli.h is generally sufficient to make all the xli resources available: ie:

\#include "xli.h"

## Identify function
The identification function is used to implement the -identify option of xli. It is generally of the form :

```
int xyyzIdent(fullname, name)

     char ∗fullname, ∗name;
{
}
```

where this is an xyyz type image loader file.

fullname is the name including path, while name is the short name of the file that is used as a title, or to refer to the file in messages.

Return 0 if the image is NOT identified.

Return 1 if the image IS identified.

If the file is identified, use a message something like:

```
printf("%s is a %dx%d xyyz image with %d colors\n",
	 name, width, height, ncolors);
```

Try and be quick about identifying the image - don't read the whole image just to identify it !

Use printf even if something is wrong with the file. Use perror for a system error - ie. unable to open file.

## Loading the image
The load function is used to identify and load the file if it is recognized. It is of the form:

```
Image xyyzLoad(fullname, image_ops, verbose)

     ImageOptions ∗image_ops;

     char         ∗fullname;

     boolean       verbose;
{
}
```

Identify the image as quickly as possible.

Return NULL if the image is not identified.

Otherwise Return a pointer to an image structure with the image in it.

If the image is properly identified, but there is something wrong with it before anything useful is read in, report the error - ie.

```
fprintf(stderr,"xyyzLoad: %s - corrupted color map\n",name);
```

clean up (ie. release the image structure and any allocated memory) and return NULL.

If the image is properly identified, and there is something wrong with it, but something useful has been read in (ie. color maps etc. have been loaded, and part of the image is loaded), report the error using fprintf (as above) and return what there is of the image.

Remember to release and temporary memory allocated on returning, whether the image is loaded ok, or if something goes wrong.

Remember to read any trailing options before returning a successfully loaded image, and before closing the file. Trailing options are read by calling the function:

```
read_trail_opt(image_ops, zf, image, verbose)

    ImageOptions ∗image_ops;

    ZFILE        ∗zf;

    Image        ∗image;

    boolean       verbose;
```

Remember to close the file before returning.

Remember to add any additional info to the image structure - ie. name, gamma if known etc.

NEVER EVER exit(). There may be other image loaders and other images to load.

Use printf to give verbose output on image details.

Use fprintf(stderr," ... "); to give error warning if the file is corrupted.

use perror for a system error - ie. unable to open file.

## Useful info in image_ops:

```
	char         ∗name;         /∗ Short name of image ∗/
```

## Useful things to set in the image structure:

```
	char         ∗title;  /∗ name of image ∗/
	RGBMap        rgb;    / RGB map of image if IRGB type ∗/
	byte         ∗data;   /∗ data, rounded to full byte for each row ∗/
	float		  gamma;	/∗ gamma of display the image is adjusted ∗/
	     		        	/∗ for, if know. ∗/
```

## Creating and destroying Image structures:
The image structure is created by a call to one of three routines:

```
/∗ For a monochrome bitmap ∗/
Image ∗newBitImage(width, height)

     unsigned int width, height;
/∗ For a color image with a color map ∗/
Image ∗newRGBImage(width, height, depth)

     unsigned int width, height, depth;
/∗ For a true color image ∗/
Image ∗newTrueImage(width, height)

     unsigned int width, height;
```

And the image can be freed with:

```
void freeImageData(image)

     Image ∗image;
```

Examine another image loader (ie. gif.c) to see how to set up a color map.

## File input resources:
A set of file input functions are available that automatically handle compressed files, and also by default buffer the file in memory to speed up the detection of the image type. The following functions are available:

```
/∗

  Open a file by name and return a pointer to

  a file descriptor.

 ∗/
ZFILE ∗zopen(name)

     char ∗name;
/∗

  Read some data into a buffer

 ∗/
int zread(zf, buf, len)

     ZFILE ∗zf;

     byte ∗buf;

     int len;
/∗

  Macro that returns a character from the file.

 ∗/
zgetc(zf)

     ZFILE ∗zf;
/∗

  Function that reads a string into a buffer

 ∗/
char ∗zgets(buf, size, zf)

     char         ∗buf;

     unsigned int  size;

     ZFILE        ∗zf;
/∗ Return the files EOF status ∗/
int zeof(zf)

     ZFILE ∗zf;
/∗

  Clear any errors (ie. EOF)

 ∗/
void zclearerr(zf)

     ZFILE ∗zf;
/∗

  Turn off caching when an image has been identified

  and there is no need to re-open it. The cached part

  of the file is still kept, but any reads past this

  point are not cached.

 ∗/
void znocache(zf)

     ZFILE ∗zf;
/∗

  Rewind the cached file. This won't work if the file

  is stdin and we have read past the cached part of

  the file. Return TRUE on success.

 ∗/
boolean zrewind(zf)

     ZFILE ∗zf;
/∗

  Return a block of data back to the input stream.

  Useful for a load routine that does its own buffering

  and wants to return what is left after it has read

  an image. (This is needed to allow trailing options

  to be recognized.) Can also be used instead of ungetc().

 ∗/
void zunread(zf, buf, len)

     ZFILE ∗zf;

     byte ∗buf;

     int len;
/∗

  Close a file.

  The file is not actually closed until zreset is called,

  in case another loader wants to re-open it.

 ∗/
void zclose(zf)

     ZFILE ∗zf;
/∗

  Really close a file. Not used by imageLoad functions.

 ∗/
void zreset(filename)

     char ∗filename;
```

Some macros are provided to facilitate reading and writing elements larger than a character from/to a data buffer according to the desired endianness:

Big endian:

```
#define memToVal(PTR,LEN)
#define valToMem(VAL,PTR,LEN)
```

Little Endian

```
#define memToValLSB(PTR,LEN)
#define valToMemLSB(VAL,PTR,LEN)
```

## Memory allocation:
The built in memory allocation routines are guaranteed not to fail.

```
/∗ Duplicate a string. Good for making up the image title etc. ∗/
char ∗dupString(s)

     char ∗s;
byte ∗lmalloc(size)

     unsigned int size;
byte ∗lcalloc(size)

     unsigned int size;
void lfree(area)

     byte ∗area;
```

Be careful not to call lfree with NULL. It may cause a fault.

## Other facilities:
Memory manipulation

```
/∗ Copy a block of memory ∗/
bcopy(S,D,N)
/∗ Zero a block of memory ∗/
bzero(P,N)
/∗ Fill a block of memory with a value ∗/
bfill(P,N,C)
```

## If all else fails:
Read the source. xli.h and image.h are a good place to start. Look at one of the existing loaders ie. pcx.c Grep for anything else!