Lines Matching full:system
5 <title>System Library</title>
10 <h1>System Library</h1>
15 <li><a href="#headers">Don't Include System Headers</a></li>
16 <li><a href="#expose">Don't Expose System Headers</a></li>
41 <p>This document provides some details on LLVM's System Library, located in
42 the source at <tt>lib/System</tt> and <tt>include/llvm/System</tt>. The
44 systems for the few services LLVM needs from the operating system. Much of
46 areas, system dependent facilities are needed and the System Library is the
47 wrapper around those system calls.</p>
48 <p>By centralizing LLVM's use of operating system interfaces, we make it
50 ported to new platforms since (theoretically) only <tt>lib/System</tt> needs
53 with simple calls to the interfaces provided in <tt>include/llvm/System</tt>.
55 <p>Note that the System Library is not intended to be a complete operating
56 system wrapper (such as the Adaptive Communications Environment (ACE) or
59 <p>The System Library was written by Reid Spencer who formulated the
61 System (XPS). Several people helped with the effort; especially,
71 portability rules associated with the System Library. Adherence to these rules
72 should help the System Library achieve its goal of shielding LLVM from the
73 variations in operating system interfaces and doing so efficiently. The
77 <h3><a name="headers">Don't Include System Headers</a></h3>
79 <p>Except in <tt>lib/System</tt>, no LLVM source code should directly
80 <tt>#include</tt> a system header. Care has been taken to remove all such
81 <tt>#includes</tt> from LLVM while <tt>lib/System</tt> was being
84 source code outside the implementation of <tt>lib/System</tt>.</p>
85 <p>To obtain system-dependent functionality, existing interfaces to the system
86 found in <tt>include/llvm/System</tt> should be used. If an appropriate
87 interface is not available, it should be added to <tt>include/llvm/System</tt>
88 and implemented in <tt>lib/System</tt> for all supported platforms.</p>
92 <h3><a name="expose">Don't Expose System Headers</a></h3>
94 <p>The System Library must shield LLVM from <em>all</em> system headers. To
95 obtain system level functionality, LLVM source must
96 <tt>#include "llvm/System/Thing.h"</tt> and nothing else. This means that
97 <tt>Thing.h</tt> cannot expose any system header files. This protects LLVM
98 from accidentally using system specific functionality and only allows it
99 via the <tt>lib/System</tt> interface.</p>
106 to be exposed through the <tt>lib/System</tt> interface. These headers and
109 <tt>lib/System</tt> interfaces.</p>
116 standard template library may be exposed through the <tt>lib/System</tt>
119 inclusion through lib/System interfaces.</p>
125 <p>The entry points specified in the interface of lib/System must be aimed at
127 simply wrap each operating system call. It would be preferable to wrap several
128 operating system calls that are always used in conjunction with one another by
132 operating system calls: <tt>getenv, fork, execve,</tt> and <tt>wait</tt>. The
133 correct thing for lib/System to provide is a function, say
135 what we don't want is wrappers for the operating system calls involved.</p>
137 system calls and the System library's interface. Any such interface function
144 <p>There must be no functionality specified in the interface of lib/System
146 operating system wrapper here, just enough to satisfy LLVM's needs. And, LLVM
147 doesn't need much. This design goal aims to keep the lib/System interface
158 systems supported for a given class of operating system (e.g. Unix, Win32).
165 <p>The System Library interfaces can be called quite frequently by LLVM. In
175 <p>Any functions defined by system libraries (i.e. not defined by lib/System)
176 must not be exposed through the lib/System interface, even if the header file
177 for that function is not exposed. This prevents inadvertent use of system
179 <p>For example, the <tt>stat</tt> system call is notorious for having
180 variations in the data it provides. <tt>lib/System</tt> must not declare
184 an implementation detail. The interface provided by the System Library must
191 <p>Any data defined by system libraries (i.e. not defined by lib/System) must
192 not be exposed through the lib/System interface, even if the header file for
200 <p>Operating system interfaces will generally provide error results for every
205 "out of space", "bad disk sector", or "system call interrupted". We'll call
208 <p>lib/System must always attempt to minimize soft errors.
218 to open the file will produce an error. However, lib/System should not
223 <p>This design principle needs to be maintained in lib/System because it
239 <p>None of the lib/System interface functions may be declared with C++
242 functions. This is a performance consideration: lib/System functions are at
245 system library should actually throw exceptions.</p>
251 <p>Implementations of the System Library interface are separated by their
252 general class of operating system. Currently only Unix and Win32 classes are
253 defined but more could be added for other operating system classifications.
254 To distinguish which implementation to compile, the code in lib/System uses
256 llvm/Config/config.h file. Each source file in lib/System, after implementing
257 the generic (operating system independent) functionality needs to include the
259 directives. For example, if we had lib/System/File.cpp, we'd expect to see in
269 <p>The implementation in lib/System/Unix/File.cpp should handle all Unix
270 variants. The implementation in lib/System/Win32/File.cpp should handle all
272 operating system that will provide the implementation. The specific details
280 <p>The implementation of a lib/System interface can vary drastically between
283 forward on all operating system. System V IPC on the other hand isn't even
284 supported on all platforms. Instead of "supporting" System V IPC, lib/System
286 communications. The implementations might use System V IPC if that was
288 given operating system. In all cases, the interface and the implementation