# AUTHOR <EMAIL@ADDRESS>, YEAR.
# 
# Translators:
msgid ""
msgstr ""
"Project-Id-Version: Defensive Coding Guide\n"
"POT-Creation-Date: 2013-03-12T03:19:44\n"
"PO-Revision-Date: 2013-03-19 15:29+0000\n"
"Last-Translator: Automatically generated\n"
"Language-Team: None\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: en_US\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

#. Tag: title
#, no-c-format
msgid "Library Design"
msgstr "Library Design"

#. Tag: para
#, no-c-format
msgid ""
"Throught this section, the term <emphasis>client code</emphasis> refers to "
"applications and other libraries using the library."
msgstr "Throught this section, the term <emphasis>client code</emphasis> refers to applications and other libraries using the library."

#. Tag: title
#, no-c-format
msgid "State management"
msgstr "State management"

#. Tag: title
#, no-c-format
msgid "Global state"
msgstr "Global state"

#. Tag: para
#, no-c-format
msgid "Global state should be avoided."
msgstr "Global state should be avoided."

#. Tag: para
#, no-c-format
msgid ""
"If this is impossible, the global state must be protected with a lock. For "
"C/C++, you can use the <function>pthread_mutex_lock</function> and "
"<function>pthread_mutex_unlock</function> functions without linking against "
"<literal>-lpthread</literal> because the system provides stubs for non-"
"threaded processes."
msgstr "If this is impossible, the global state must be protected with a lock. For C/C++, you can use the <function>pthread_mutex_lock</function> and <function>pthread_mutex_unlock</function> functions without linking against <literal>-lpthread</literal> because the system provides stubs for non-threaded processes."

#. Tag: para
#, no-c-format
msgid ""
"For compatibility with <function>fork</function>, these locks should be "
"acquired and released in helpers registered with "
"<function>pthread_atfork</function>. This function is not available without "
"<literal>-lpthread</literal>, so you need to use <function>dlsym</function> "
"or a weak symbol to obtain its address."
msgstr "For compatibility with <function>fork</function>, these locks should be acquired and released in helpers registered with <function>pthread_atfork</function>. This function is not available without <literal>-lpthread</literal>, so you need to use <function>dlsym</function> or a weak symbol to obtain its address."

#. Tag: para
#, no-c-format
msgid ""
"If you need <function>fork</function> protection for other reasons, you "
"should store the process ID and compare it to the value returned by "
"<function>getpid</function> each time you access the global state. "
"(<function>getpid</function> is not implemented as a system call and is "
"fast.) If the value changes, you know that you have to re-create the state "
"object. (This needs to be combined with locking, of course.)"
msgstr "If you need <function>fork</function> protection for other reasons, you should store the process ID and compare it to the value returned by <function>getpid</function> each time you access the global state. (<function>getpid</function> is not implemented as a system call and is fast.) If the value changes, you know that you have to re-create the state object. (This needs to be combined with locking, of course.)"

#. Tag: title
#, no-c-format
msgid "Handles"
msgstr "Handles"

#. Tag: para
#, no-c-format
msgid ""
"Library state should be kept behind a curtain. Client code should receive "
"only a handle. In C, the handle can be a pointer to an incomplete "
"<literal>struct</literal>. In C++, the handle can be a pointer to an "
"abstract base class, or it can be hidden using the pointer-to-implementation"
" idiom."
msgstr "Library state should be kept behind a curtain. Client code should receive only a handle. In C, the handle can be a pointer to an incomplete <literal>struct</literal>. In C++, the handle can be a pointer to an abstract base class, or it can be hidden using the pointer-to-implementation idiom."

#. Tag: para
#, no-c-format
msgid ""
"The library should provide functions for creating and destroying handles. "
"(In C++, it is possible to use virtual destructors for the latter.) "
"Consistency between creation and destruction of handles is strongly "
"recommended: If the client code created a handle, it is the responsibility "
"of the client code to destroy it. (This is not always possible or "
"convenient, so sometimes, a transfer of ownership has to happen.)"
msgstr "The library should provide functions for creating and destroying handles. (In C++, it is possible to use virtual destructors for the latter.) Consistency between creation and destruction of handles is strongly recommended: If the client code created a handle, it is the responsibility of the client code to destroy it. (This is not always possible or convenient, so sometimes, a transfer of ownership has to happen.)"

#. Tag: para
#, no-c-format
msgid ""
"Using handles ensures that it is possible to change the way the library "
"represents state in a way that is transparent to client code. This is "
"important to facilitate security updates and many other code changes."
msgstr "Using handles ensures that it is possible to change the way the library represents state in a way that is transparent to client code. This is important to facilitate security updates and many other code changes."

#. Tag: para
#, no-c-format
msgid ""
"It is not always necessary to protect state behind a handle with a lock. "
"This depends on the level of thread safety the library provides."
msgstr "It is not always necessary to protect state behind a handle with a lock. This depends on the level of thread safety the library provides."

#. Tag: title
#, no-c-format
msgid "Object orientation"
msgstr "Object orientation"

#. Tag: para
#, no-c-format
msgid ""
"Classes should be either designed as base classes, or it should be "
"impossible to use them as base classes (like <literal>final</literal> "
"classes in Java). Classes which are not designed for inheritance and are "
"used as base classes nevertheless create potential maintenance hazards "
"because it is difficult to predict how client code will react when calls to "
"virtual methods are added, reordered or removed."
msgstr "Classes should be either designed as base classes, or it should be impossible to use them as base classes (like <literal>final</literal> classes in Java). Classes which are not designed for inheritance and are used as base classes nevertheless create potential maintenance hazards because it is difficult to predict how client code will react when calls to virtual methods are added, reordered or removed."

#. Tag: para
#, no-c-format
msgid ""
"Virtual member functions can be used as callbacks. See <xref linkend=\"sect-"
"Defensive_Coding-Tasks-Library_Design-Callbacks\" /> for some of the "
"challenges involved."
msgstr "Virtual member functions can be used as callbacks. See <xref linkend=\"sect-Defensive_Coding-Tasks-Library_Design-Callbacks\" /> for some of the challenges involved."

#. Tag: title
#, no-c-format
msgid "Callbacks"
msgstr "Callbacks"

#. Tag: para
#, no-c-format
msgid ""
"Higher-order code is difficult to analyze for humans and computers alike, so"
" it should be avoided. Often, an iterator-based interface (a library "
"function which is called repeatedly by client code and returns a stream of "
"events) leads to a better design which is easier to document and use."
msgstr "Higher-order code is difficult to analyze for humans and computers alike, so it should be avoided. Often, an iterator-based interface (a library function which is called repeatedly by client code and returns a stream of events) leads to a better design which is easier to document and use."

#. Tag: para
#, no-c-format
msgid "If callbacks are unavoidable, some guidelines for them follow."
msgstr "If callbacks are unavoidable, some guidelines for them follow."

#. Tag: para
#, no-c-format
msgid ""
"In modern C++ code, <literal>std::function</literal> objects should be used "
"for callbacks."
msgstr "In modern C++ code, <literal>std::function</literal> objects should be used for callbacks."

#. Tag: para
#, no-c-format
msgid ""
"In older C++ code and in C code, all callbacks must have an additional "
"closure parameter of type <literal>void *</literal>, the value of which can "
"be specified by client code. If possible, the value of the closure parameter"
" should be provided by client code at the same time a specific callback is "
"registered (or specified as a function argument). If a single closure "
"parameter is shared by multiple callbacks, flexibility is greatly reduced, "
"and conflicts between different pieces of client code using the same library"
" object could be unresolvable. In some cases, it makes sense to provide a "
"de-registration callback which can be used to destroy the closure parameter "
"when the callback is no longer used."
msgstr "In older C++ code and in C code, all callbacks must have an additional closure parameter of type <literal>void *</literal>, the value of which can be specified by client code. If possible, the value of the closure parameter should be provided by client code at the same time a specific callback is registered (or specified as a function argument). If a single closure parameter is shared by multiple callbacks, flexibility is greatly reduced, and conflicts between different pieces of client code using the same library object could be unresolvable. In some cases, it makes sense to provide a de-registration callback which can be used to destroy the closure parameter when the callback is no longer used."

#. Tag: para
#, no-c-format
msgid ""
"Callbacks can throw exceptions or call <function>longjmp</function>. If "
"possible, all library objects should remain in a valid state. (All further "
"operations on them can fail, but it should be possible to deallocate them "
"without causing resource leaks.)"
msgstr "Callbacks can throw exceptions or call <function>longjmp</function>. If possible, all library objects should remain in a valid state. (All further operations on them can fail, but it should be possible to deallocate them without causing resource leaks.)"

#. Tag: para
#, no-c-format
msgid ""
"The presence of callbacks raises the question if functions provided by the "
"library are <emphasis>reentrant</emphasis>. Unless a library was designed "
"for such use, bad things will happen if a callback function uses functions "
"in the same library (particularly if they are invoked on the same objects "
"and manipulate the same state). When the callback is invoked, the library "
"can be in an inconsistent state. Reentrant functions are more difficult to "
"write than thread-safe functions (by definition, simple locking would "
"immediately lead to deadlocks). It is also difficult to decide what to do "
"when destruction of an object which is currently processing a callback is "
"requested."
msgstr "The presence of callbacks raises the question if functions provided by the library are <emphasis>reentrant</emphasis>. Unless a library was designed for such use, bad things will happen if a callback function uses functions in the same library (particularly if they are invoked on the same objects and manipulate the same state). When the callback is invoked, the library can be in an inconsistent state. Reentrant functions are more difficult to write than thread-safe functions (by definition, simple locking would immediately lead to deadlocks). It is also difficult to decide what to do when destruction of an object which is currently processing a callback is requested."

#. Tag: title
#, no-c-format
msgid "Process attributes"
msgstr "Process attributes"

#. Tag: para
#, no-c-format
msgid ""
"Several attributes are global and affect all code in the process, not just "
"the library that manipulates them."
msgstr "Several attributes are global and affect all code in the process, not just the library that manipulates them."

#. Tag: para
#, no-c-format
msgid ""
"environment variables (see <xref linkend=\"sect-Defensive_Coding-Tasks-"
"secure_getenv\" />)"
msgstr "environment variables (see <xref linkend=\"sect-Defensive_Coding-Tasks-secure_getenv\" />)"

#. Tag: para
#, no-c-format
msgid "umask"
msgstr "umask"

#. Tag: para
#, no-c-format
msgid "user IDs, group IDs and capabilities"
msgstr "user IDs, group IDs and capabilities"

#. Tag: para
#, no-c-format
msgid "current working directory"
msgstr "current working directory"

#. Tag: para
#, no-c-format
msgid "signal handlers, signal masks and signal delivery"
msgstr "signal handlers, signal masks and signal delivery"

#. Tag: para
#, no-c-format
msgid ""
"file locks (especially <function>fcntl</function> locks behave in surprising"
" ways, not just in a multi-threaded environment)"
msgstr "file locks (especially <function>fcntl</function> locks behave in surprising ways, not just in a multi-threaded environment)"

#. Tag: para
#, no-c-format
msgid ""
"Library code should avoid manipulating these global process attributes. It "
"should not rely on environment variables, umask, the current working "
"directory and signal masks because these attributes can be inherted from an "
"untrusted source."
msgstr "Library code should avoid manipulating these global process attributes. It should not rely on environment variables, umask, the current working directory and signal masks because these attributes can be inherted from an untrusted source."

#. Tag: para
#, no-c-format
msgid ""
"In addition, there are obvious process-wide aspects such as the virtual "
"memory layout, the set of open files and dynamic shared objects, but with "
"the exception of shared objects, these can be manipulated in a relatively "
"isolated way."
msgstr "In addition, there are obvious process-wide aspects such as the virtual memory layout, the set of open files and dynamic shared objects, but with the exception of shared objects, these can be manipulated in a relatively isolated way."
