Date: Thu, 12 Jul 2012 14:12:49 +0000 (UTC) From: Isabell Long <issyl0@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39189 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201207121412.q6CECngA011553@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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><stdint.h></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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201207121412.q6CECngA011553>