\documentclass{article} \usepackage{fullpage} \usepackage{graphicx} \title{The Perforce Protocol} \author{David Maze} \begin{document} \maketitle \section{Introduction} Perforce is a commercial Source Control Management (SCM) tool. A centralized server keeps one or more ``depots'', each containing revision history for a set of files under its control. Client machines contact the server to check files in or out, and to get information about the server or the filest in it. This paper documents the network protocol used by Perforce. The command-line \texttt{p4} client speaks this protocol to a Perforce server. The client and server exchange information until the server announces that the session ends, at which point the client closes the connection. \section{Structure} The client and server each use the same data format when exchanging information. Data is sent in packets, and each packet contains several pairs of keys and associated data. The data can be arbitrary binary data, but whenever possible Perforce uses plain-text data. The keys are always plain ASCII text. Occasionally the protocol will include a raw number, generally as the length of a packet or of a pair's data. These numbers are always four bytes long, and in little-endian format. Note that this is the opposite of the ``network byte order'' widely used in Internet programming. The packet format is shown in Figure \ref{fig:packet}. A packet begins with a one-byte checksum, followed by the length of the packet. The checksum is the bitwise XOR of the four packet length bytes; for a packet less than 256 bytes, the checksum is equal to the first length byte, and the remaining three length bytes are zeroes. \begin{figure}[htb] \begin{center} \includegraphics{packet.eps} \caption{Perforce packet format} \label{fig:packet} \end{center} \end{figure} The body of the packet contains a list of pairs; the format of each pair is shown in Figure \ref{fig:pair}. The pair begins with a plain-text, null-terminated key. The key may have zero length, in which case the first byte of the packet is a zero. The key is followed by a four-byte length. This is followed by the actual data and a terminating null. Note that the null follows the data, even if the data is binary. If the data consists of plain text, the length only counts the actual characters; the terminating null is part of the protocol, which appears to serve as a convenience for implementors. \begin{figure}[htb] \begin{center} \includegraphics{pair.eps} \caption{Key/data pair format} \label{fig:pair} \end{center} \end{figure} \section{Semantics} The server and client exchange packets of the format described above. The command-line \texttt{p4} client is a dumb client that knows nothing more than how to implement the protocol; it is possible to add functionality to Perforce by upgrading the server, or by adding an intermediary which knows how to process some extended commands. Each exchanged packet ends with a pair with the key \verb|func|. This describes the function to be performed as a result of the packet. Other data that is exchanged depends on what function is provided. If the server sends a packet with an output function request, for example, a \verb|data| pair will contain the text that is to be output. The client and server begin by exchanging protocol versions. Each sends a \verb|protocol| packet to the other. Present implementations of the \texttt{p4} client send an empty \verb|cmpfile| key and a \verb|client| key with a value of ``8''; \texttt{p4d} sends the pairs \verb|xfiles| 4, \verb|server| 3, and \verb|server2| 8. The client then sends the user command request to the server. The packet begins with a series of null-keyed pairs containing the command line arguments. If the user types \textsf{p4 help commands}, for example, the packet would begin with a pair with no key and a body of ``commands''. The packet also contains a series of informational pairs, for \verb|client|, \verb|cwd|, \verb|host|, \verb|os|, and \verb|user|; these contain the Perforce client name, the client's current working directory, the host name and its operating system, and the Perforce user name, respectively. The packet ends with a \verb|func| pair of the form ``user-\emph{command}''; for the help example earlier, the function would be ``user-help''. The server responds with packets telling the client to do various things. Depending on the function, the client may or may not respond to each. The client may be asked to present information to the user, or to modify and return a particular form. The exchange ends when the server sends a packet with ``release'' as its function. The client responds by sending a packet with function ``release2'' and closing the network connection. Note that the server never closes the network connection; the client always closes the connection when it believes the session is over. \end{document}
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#1 | 450 | sandy_currier |
Initial import of p4filter code. This contains a solaris2.6 binary but no others. |