svn commit: r39189 - head/en_US.ISO8859-1/books/porters-handbook

[Isabell Long]

Author: issyl0
Date: Thu Jul 12 14:12:49 2012
New Revision: 39189
URL: http://svn.freebsd.org/changeset/doc/39189

Log:
  Add a section to the Dos and Don'ts section of the porter's handbook
  about avoiding Linuxisms.
  
  Submitted by:	issyl0 (as part of Google Code-In 2011)
  Reviewed by:	eadler
  Approved by:	gabor (mentor)

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/book.sgml

Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.sgml	Thu Jul 12 13:19:23 2012	(r39188)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.sgml	Thu Jul 12 14:12:49 2012	(r39189)
@@ -16059,6 +16059,77 @@ IGNORE=	POINTYHAT is not supported
 	and confirm the changes with them.</para>
     </sect1>
 
+    <sect1 id="dads-avoiding-linuxisms">
+      <title>Avoiding Linuxisms</title>
+
+      <para>Do not use <filename>/proc</filename> if there are any
+	other ways of getting the information, e.g.
+	<function>setprogname(argv[0])</function> in
+	<function>main()</function> and then &man.getprogname.3; if you
+	want to <quote>know your name</quote>.</para>
+
+      <para>Do not rely on behaviour that is undocumented by
+	<acronym>POSIX</acronym>.</para>
+
+      <para>Do not record timestamps in the critical path of the
+	application if it also works without.  Getting timestamps may
+	be slow, depending on the accuracy of timestamps in the
+	<acronym>OS</acronym>.  If timestamps are really needed,
+	determine how precise they have to be and use an
+	<acronym>API</acronym> which is documented to just deliver the
+	needed precision.</para>
+
+      <para>A number of simple syscalls (for example
+	&man.gettimeofday.2;, &man.getpid.2;) are much faster on
+	&linux; than on any other operating system due to caching and
+	the vsyscall performance optimizations.  Do not rely on them
+	being cheap in performance-critical applications.  In general,
+	try hard to avoid syscalls if possible.</para>
+
+      <para>Do not rely on &linux;-specific socket behaviour.  In
+	particular, default socket buffer sizes are different (call
+	&man.setsockopt.2; with <literal>SO_SNDBUF</literal> and
+	<literal>SO_RCVBUF</literal>, and while &linux;'s &man.send.2;
+	blocks when the socket buffer is full, &os;'s will fail and
+	set <literal>ENOBUFS</literal> in errno.</para>
+
+      <para>If relying on non-standard behaviour is required,
+	encapsulate it properly into a generic <acronym>API</acronym>,
+	do a check for the behaviour in the configure stage, and stop
+	if it is missing.</para>
+
+      <para>Check the <ulink
+	url="http://www.freebsd.org/cgi/man.cgi">man pages</ulink> to
+	see if the function used is a <acronym>POSIX</acronym>
+	interface (in the <quote>STANDARDS</quote> section of the man
+	page).</para>
+
+      <para>Do not assume that <filename>/bin/sh</filename> is
+	<application>bash</application>.  Ensure that a command line
+	passed to &man.system.3; will work with a
+	<acronym>POSIX</acronym> compliant shell.</para>
+
+      <para>A list of common <application>bash</application>isms is
+	available <ulink
+	url="https://wiki.ubuntu.com/DashAsBinSh">here</ulink>.</para>
+
+      <para>Do not <literal>#include
+	<filename>&lt;stdint.h&gt;</filename></literal> if
+	<filename>inttypes.h</filename> is sufficient.  This will
+	ensure that the software builds on older versions of
+	&os;.</para>
+
+      <para>Check that headers are included in the
+	<acronym>POSIX</acronym> or man page recommended way, e.g.
+	<filename>sys/types.h</filename> is often forgotten, which is
+	not as much of a problem for &linux; as it is for &os;.</para>
+
+      <para>Compile threaded applications with
+	<quote>-pthread</quote>, not <quote>-lpthread</quote> or
+	variations thereof.</para>
+
+    </sect1>
+
     <sect1 id="dads-misc">
       <title>Miscellanea</title>