<title>APT Cache File Format</title>
<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: cache.sgml,v 1.8 2001/02/20 07:03:17 jgg Exp $</version>
+<version>$Id: cache.sgml,v 1.9 2001/04/04 05:00:14 jgg Exp $</version>
<abstract>
This document describes the complete implementation and format of the APT
file.
<p>
-Please understand, this is designed as a -CACHE FILE- it is not ment to be
-used on any system other than the one it was created for. It is not ment to
-be authoritative either, ie if a system crash or software failure occures it
-must be perfectly acceptable for the cache file to be in an inconsistant
+Please understand, this is designed as a -CACHE FILE- it is not meant to be
+used on any system other than the one it was created for. It is not meant to
+be authoritative either, i.e. if a system crash or software failure occurs it
+must be perfectly acceptable for the cache file to be in an inconsistent
state. Furthermore at any time the cache file may be erased without losing
any information.
<p>
To keep memory use down the cache file only contains often used fields and
-fields that are inexepensive to store, the Package file has a full list of
+fields that are inexpensive to store, the Package file has a full list of
fields. Also the client may assume that all items are perfectly valid and
need not perform checks against their correctness. Removal of information
from the cache is possible, but blanks will be left in the file, and
by taking the index, multiplying it by the type size and then adding
it to the start address of the memory block. This sounds complex, but
in C it is a single array dereference. Because all items are aligned to
-their size and indexs are stored as multiples of the size of the structure
+their size and indexes are stored as multiples of the size of the structure
the format is immediately portable to all possible architectures - BUT the
generated files are -NOT-.
<tag>VerFileSz
<tag>ProvidesSz<item>
*Sz contains the sizeof() that particular structure. It is used as an
-extra consistancy check on the structure of the file.
+extra consistency check on the structure of the file.
If any of the size values do not exactly match what the client expects then
the client should refuse the load the file.
<tag>VersionCount
<tag>DependsCount
<tag>PackageFileCount<item>
-These indicate the number of each structure contianed in the cache.
+These indicate the number of each structure contained in the cache.
PackageCount is especially useful for generating user state structures.
See Package::Id for more info.
<tag>VerSysName<item>
-String representing the versiong system used for this cache
+String representing the version system used for this cache
<tag>Architecture<item>
Architecture the cache was built against.
<tag>MaxVerFileSize<item>
The maximum size of a raw entry from the original Package file
-(ie VerFile::Size) is stored here.
+(i.e. VerFile::Size) is stored here.
<tag>FileList<item>
This contains the index of the first PackageFile structure. The PackageFile
-structures are singely linked lists that represent all package files that
+structures are singly linked lists that represent all package files that
have been merged into the cache.
<tag>StringList<item>
</example>
<p>
By iterating over each entry in the hash table it is possible to iterate over
-the entire list of packages. Hash Collisions are handled with a singely linked
+the entire list of packages. Hash Collisions are handled with a singly linked
list of packages based at the hash item. The linked list contains only
-packages that macth the hashing function.
+packages that match the hashing function.
</taglist>
<!-- }}} -->
<!-- ===================================================================== -->
<sect>Package
<p>
-This contians information for a single unique package. There can be any
+This contains information for a single unique package. There can be any
number of versions of a given package. Package exists in a singly
linked list of package records starting at the hash index of the name in
the Header->HashTable.
Name of the package.
<tag>VersionList<item>
-Base of a singely linked list of version structures. Each structure
+Base of a singly linked list of version structures. Each structure
represents a unique version of the package. The version structures
contain links into PackageFile and the original text file as well as
-detailed infromation about the size and dependencies of the specific
+detailed information about the size and dependencies of the specific
package. In this way multiple versions of a package can be cleanly handled
-by the system. Furthermore, this linked list is guarenteed to be sorted
+by the system. Furthermore, this linked list is guaranteed to be sorted
from Highest version to lowest version with no duplicate entries.
<tag>CurrentVer<item>
<tag>SelectedState
<tag>InstState
<tag>CurrentState<item>
-These corrispond to the 3 items in the Status field found in the status
+These correspond to the 3 items in the Status field found in the status
file. See the section on defines for the possible values.
<p>
SelectedState is the state that the user wishes the package to be
in.
<p>
InstState is the installation state of the package. This normally
-should be Ok, but if the installation had an accident it may be otherwise.
+should be OK, but if the installation had an accident it may be otherwise.
<p>
CurrentState indicates if the package is installed, partially installed or
not installed.
<!-- ===================================================================== -->
<sect>PackageFile
<p>
-This contians information for a single package file. Package files are
+This contains information for a single package file. Package files are
referenced by Version structures. This is a singly linked list based from
Header.FileList
<example>
<!-- ===================================================================== -->
<sect>Version
<p>
-This contians the information for a single version of a package. This is a
-singley linked list based from Package.Versionlist.
+This contains the information for a single version of a package. This is a
+single linked list based from Package.Versionlist.
<p>
The version list is always sorted from highest version to lowest version by
<tag>Size
<tag>InstalledSize<item>
-The archive size for this version. For debian this is the size of the .deb
+The archive size for this version. For Debian this is the size of the .deb
file. Installed size is the uncompressed size for this version
<tag>Hash<item>
This is a characteristic value representing this package. No two packages
-in existance should have the same VerStr and Hash with different contents.
+in existence should have the same VerStr and Hash with different contents.
<tag>ID<item>
See Package::ID.
<p>
Different section names on different versions is supported, but I
-do not expect to use it. To simplify the GUI it will mearly use the section
+do not expect to use it. To simplify the GUI it will merely use the section
in the Package structure. This should be okay as I hope sections do not change
much.
<p>
Caching of the info/*.list is an excellent place to start, by generating all
the list files into a tree structure and reverse linking them to the package
-structures in the main cache file major speed gains in dpkg might be achived.
+structures in the main cache file major speed gains in dpkg might be achieved.
<!-- }}} -->
<name>Manoj Srivastava</name>
<email>srivasta@debian.org</email>
</author>
- <version>$Id: design.sgml,v 1.1 1998/07/02 02:58:12 jgg Exp $</version>
+ <version>$Id: design.sgml,v 1.2 2001/04/04 05:00:15 jgg Exp $</version>
<abstract>
This document is an overview of the specifications and design
goals of the APT project. It also attempts to give a broad
allowing the removal of packages that left the system in
an untenable state by breaking the dependencies on
packages that were dependent on the package being
- removed. A special emhasis is placed on handling
+ removed. A special emphasis is placed on handling
pre-dependencies correctly; the target of a
predependency has to be fully configured before
attempting to install the pre-dependent package. Also,
Handle source lists for updates from multiple
sources. APT should also be able to handle diverse
methods of acquiring new packages; local filesystem,
- mountable CD-ROM drives, FTP accesible repositories are
+ mountable CD-ROM drives, FTP accessible repositories are
some of the methods that come to mind. Also, the source
lists can be separated into categories, such as main,
contrib, non-us, non-local, non-free, my-very-own,
- etc. APT should be set up to retrive the Packages
+ etc. APT should be set up to retrieve the Packages
files from these multiple source lists, as well as
retrieving the packages themselves. </p>
</item>
<p>
Take the order of installations and removals and build
up a stream of events to send to the packaging system
- (dpkg). Execute the list of events if succesful. Do not
+ (dpkg). Execute the list of events if successful. Do not
partially install packages and leave system in broken
state. Go to The Selection step as needed.</p>
</item>
<p>
Distinct versions of the same package are recorded
separately, but if multiple Packages files contain the
- same version of a package, then only the forst one is
+ same version of a package, then only the first one is
recorded. For this reason, the least expensive update
source should be listed first (local file system is
better than a remote ftp site)</p>
<item>
<p>Create an ordering of the actions to be taken.</p>
</item>
- <tag>Event genrator</tag>
+ <tag>Event generator</tag>
<item>
<p>module to interact with dpkg</p>
</item>
<title>APT Files</title>
<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: files.sgml,v 1.8 2001/02/20 07:03:17 jgg Exp $</version>
+<version>$Id: files.sgml,v 1.9 2001/04/04 05:00:15 jgg Exp $</version>
<abstract>
This document describes the complete implementation and format of the
contrib, non-free or non-us. The format for the deb line is as follows:
<p>
- deb <var>uri</var> <var>distribution</var> <var>compontent</var>
+ deb <var>uri</var> <var>distribution</var> <var>component</var>
[<var>component</var> ...]
<p>
necessary to list a number of deb lines for the same URI. APT will
sort the URI list after it has generated a complete set to allow
connection reuse. It is important to order things in the sourcelist
- from most prefered to least prefered (fastest to slowest).
+ from most preferred to least preferred (fastest to slowest).
</sect1>
<sect1>URI specification
<taglist>
<tag>cdrom<item>
- The cdrom scheme is special in that If Modifed Since queries are never
+ The cdrom scheme is special in that If Modified Since queries are never
performed and that APT knows how to match a cdrom to the name it
was given when first inserted. APT also knows all of the possible
mount points the cdrom drives and that the user should be prompted
to insert a CD if it cannot be found. The path is relative to an
- arbitary mount point (of APT's choosing) and must not start with a
+ arbitrary mount point (of APT's choosing) and must not start with a
slash. The first pathname component is the given name and is purely
descriptive and of the users choice. However, if a file in the root of
the cdrom is called '.disk/info' its contents will be used instead of
</example>
<tag>http<item>
- This scheme specifies a HTTP server for the debian archive. HTTP is prefered
+ This scheme specifies a HTTP server for the debian archive. HTTP is preferred
over FTP because If Modified Since queries against the Package file are
possible as well as deep pipelining and resume capabilities.
<example>
</example>
<tag>file<item>
- The file scheme allows an arbitary directory in the file system to be
+ The file scheme allows an arbitrary directory in the file system to be
considered as a debian archive. This is useful for NFS mounts and
local mirrors/archives.
<example>
<sect1>Hashing the URI
<p>
-All permanent information aquired from any of the sources is stored in the
+All permanent information acquired from any of the sources is stored in the
lists directory. Thus, there must be a way to relate the filename in the
lists directory to a line in the sourcelist. To simplify things this is
done by quoting the URI and treating _'s as quoteable characters and
converting / to _. The URI spec says this is done by converting a
sensitive character into %xx where xx is the hexadecimal representation
-from the ascii character set. Examples:
+from the ASCII character set. Examples:
<example>
http://www.debian.org/archive/dists/stable/binary-i386/Packages
The extra status file serves the same purpose as the normal dpkg status file
(/var/lib/dpkg/status) except that it stores information unique to apt.
This includes the autoflag, target distribution and version and any other
-uniqe features that come up over time. It duplicates nothing from the normal
+unique features that come up over time. It duplicates nothing from the normal
dpkg status file. Please see other APT documentation for a discussion
-of the exact internal behavior of these fields. The Package field is
+of the exact internal behaviour of these fields. The Package field is
placed directly before the new fields to indicate which package they
apply to. The new fields are as follows:
<p>
The archives directory is where all downloaded .deb archives go. When the
file transfer is initiated the deb is placed in partial. Once the file
-is fully downloaded and its MD5 hash and size are verifitied it is moved
+is fully downloaded and its MD5 hash and size are verified it is moved
from partial into archives/. Any files found in archives/ can be assumed
to be verified.
<p>
-No dirctory structure is transfered from the receiving site and all .deb
+No directory structure is transfered from the receiving site and all .deb
file names conform to debian conventions. No short (msdos) filename should
be placed in archives. If the need arises .debs should be unpacked, scanned
and renamed to their correct internal names. This is mostly to prevent
<taglist>
<tag>Site<item>
This is the proper host name of the site. It should not be a host within
-debian.org and generally cnames should be advoided here.
+debian.org and generally cnames should be avoided here.
<tag>Aliases<item>
These list any commonly used aliases for the site. This field is used to make
The Archive field gives the path(s) to the debian archive. [access]
specifies the access method and may be one of ftp, http, rsync, nfs, or
smb. For many of the types it is possible to prefix the path with :###
-indicating that an alternate port should be used. Generaly paths
+indicating that an alternate port should be used. Generally paths
start with a / and end with a /, rsync is an exception in that the
first directory component is not a path but a label.
<em>unstable</>.
<tag>Component<item>
-Referes to the sub-component of the archive, <em>main</>, <em>contrib</>
+Refers to the sub-component of the archive, <em>main</>, <em>contrib</>
etc. Component may be omitted if there are no components for this archive.
<tag>Version<item>
<example>
Archive: stable
-Compontent: main
+Component: main
Version: 1.3.1r6
Origin: Debian
Label: Debian
And unstable,
<example>
Archive: unstable
-Compontent: main
+Component: main
Version: 2.1
Origin: Debian
Label: Debian
<title>APT Method Interface </title>
<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: method.sgml,v 1.7 1999/10/18 00:37:36 jgg Exp $</version>
+<version>$Id: method.sgml,v 1.8 2001/04/04 05:00:15 jgg Exp $</version>
<abstract>
This document describes the interface that APT uses to the archive
<tag>acquire<item>
The act of bring a URI into the local pathname space. This may simply
-be verifiying the existence of the URI or actually downloading it from
+be verifying the existence of the URI or actually downloading it from
a remote site.
</taglist>
<p>
All methods operate as a sub process of a main controlling parent. 3 FD's
are opened for use by the method allowing two way communication and
-emergency error reporting. The FD's corrispond to the well known unix FD's,
+emergency error reporting. The FD's correspond to the well known unix FD's,
stdin, stdout and stderr.
<p>
-Throught operation of the method communication is done via http
+Through operation of the method communication is done via http
style plain text. Specifically RFC-822 (like the Package file) fields
are used to describe items and a numeric-like header is used to indicate
what is happening. Each of these distinct communication messages should be
<p>
The first line of each message is called the message header. The first
3 digits (called the Status Code) have the usual meaning found in the
-http protocol. 1xx is informational, 2xx is successfull and 4xx is failure.
+http protocol. 1xx is informational, 2xx is successful and 4xx is failure.
The 6xx series is used to specify things sent to the method. After the
status code is an informational string provided for visual debugging.
Only the 6xx series of status codes is sent TO the method. Furthermore
the method may not emit status codes in the 6xx range. The Codes 402
and 403 require that the method continue reading all other 6xx codes
-until the proper 602/603 code is recieved. This means the method must be
+until the proper 602/603 code is received. This means the method must be
capable of handling an unlimited number of 600 messages.
<p>
<em>100 Capabilities</> and APT sending out a <em>601 Configuration</>.
After that APT begins sending <em>600 URI Acquire</> and the method
sends out <em>200 URI Start</>, <em>201 URI Done</> or
-<em>400 URI Failure</>. No syncronization is performed, it is expected
+<em>400 URI Failure</>. No synchronization is performed, it is expected
that APT will send <em>600 URI Acquire</> messages at -any- time and
that the method should queue the messages. This allows methods like http
to pipeline requests to the remote server. It should be noted however
-that APT will buffer messages so it is not neccessary for the method
-to be constantly ready to recieve them.
+that APT will buffer messages so it is not necessary for the method
+to be constantly ready to receive them.
</sect>
<!-- }}} -->
<!-- Header Fields {{{ -->
<tag>Single-Instance<item>Requires that only one instance of the method be run
This is a yes/no value.
<tag>Pipeline<item>The method is capable of pipelining.
-<tag>Local<item>The method only returns Filename: feilds.
+<tag>Local<item>The method only returns Filename: fields.
<tag>Send-Config<item>Send configuration to the method.
<tag>Needs-Cleanup<item>The process is kept around while the files it returned
are being used. This is primarily intended for CDROM and File URIs that need
<taglist>
<tag>100 Capabilities<item>
Displays the capabilities of the method. Methods should set the
-pipeline bit if their underlying protocol supports pipeling. The
+pipeline bit if their underlying protocol supports pipelining. The
only known method that does support pipelining is http.
Fields: Version, Single-Instance, Pre-Scan, Pipeline, Send-Config,
Needs-Cleanup
<tag>102 Status<item>
Message gives a progress indication for the method. It can be used to show
-pre-transfer status for internet type methods.
+pre-transfer status for Internet type methods.
Fields: Message
<tag>200 URI Start<item>
mean no data was transfered but the file is now available. A Filename
field is specified when the URI is directly available in the local
pathname space. APT will either directly use that file or copy it into
-another location. It is possible to return Alt-* feilds to indicate that
+another location. It is possible to return Alt-* fields to indicate that
another possibility for the URI has been found in the local pathname space.
This is done if a decompressed version of a .gz file is found.
Fields: URI, Size, Last-Modified, Filename, MD5-Hash
<tag>400 URI Failure<item>
Indicates a fatal URI failure. The URI is not retrievable from this source.
-As with <em>201 URI Done</> <em>200 URI Start</> is not required to preceed
+As with <em>201 URI Done</> <em>200 URI Start</> is not required to precede
this message
Fields: URI, Message
<tag>401 General Failure<item>
-Indicates that some unspecific failure has occured and the method is unable
+Indicates that some unspecific failure has occurred and the method is unable
to continue. The method should terminate after sending this message. It
is intended to check for invalid configuration options or other severe
conditions.
projects / apt.git / commitdiff
