diff options
author | Isabell Long <issyl0@FreeBSD.org> | 2012-07-12 14:12:49 +0000 |
---|---|---|
committer | Isabell Long <issyl0@FreeBSD.org> | 2012-07-12 14:12:49 +0000 |
commit | f9f86fc0fe3b4f25e6e2ed4cfa68d1bf7725ac9c (patch) | |
tree | edf79d3019ee3614e8ff2b16cdb621f70ed5bb36 /en_US.ISO8859-1/books/porters-handbook/book.sgml | |
parent | ab815fd74f5afac315121cdc3d568e4b70cc4a26 (diff) | |
download | doc-f9f86fc0fe3b4f25e6e2ed4cfa68d1bf7725ac9c.tar.gz doc-f9f86fc0fe3b4f25e6e2ed4cfa68d1bf7725ac9c.zip |
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)
Notes
Notes:
svn path=/head/; revision=39189
Diffstat (limited to 'en_US.ISO8859-1/books/porters-handbook/book.sgml')
-rw-r--r-- | en_US.ISO8859-1/books/porters-handbook/book.sgml | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml index 0816b3ad0b..9b7ae32300 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml @@ -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> |