In my previous entry about BSD compatibility gap closure process I have promised to provide a guide on how to get new code into libc. I will use changes done via CR 6495220 to illustrate the process with examples.

Process related and technical changes which are usually needed:

• get PSARC case done
  
• File a CR to create a manual page according to the man page draft supplied with the PSARC case. You will probably need to go through the functions being added and assign them MT-Level according to attributes(5) man page (if this was not done prior to filing the PSARC case).
• actually add the code into libc
  This includes moving/introducing files from the SCM point of view and doing necessary changes to the Makefiles.
  In terms of symbols, the functions need to be actually delivered twice. Once as underscored (strong) symbol and second as WEAK alias to the strong symbol. This allows libraries use their own private implementation of the functions. (This is because the weak symbol is silently overridden by the private symbol in runtime linker)
• add entries to c_synonyms.h and synonyms.h
  synonyms.h is used in libc for symbol alias contruction (see above). c_synonyms.h provides access to underscored symbols for other (non-libc) libraries. This provides a way how to call the underscored symbols directly without risking namespace clashes/pollution.
  This step is actually needed to be used in conjunction with the previous step. nm(1) can be used to check this worked as expected:

  $ nm -x /usr/lib/libc.so.1 | grep '|_\?err$'
  [5783] |0x00049c40|0x00000030|FUNC |GLOB |0  |13 |_err
  [6552] |0x00049c40|0x00000030|FUNC |WEAK |0  |13 |err
  

• Do the necessary packaging changes
  If you're adding new header file change SUNWhea's prototype_* files (most probably just prototype_com)
  If the file was previously installed into proto area during build it needs to be removed from the exception files (for i386 and sparc).
• modify lib's mapfile
  This is needed for the symbols to become visible and versioned. Public symbols belong to the latest SUNW section. After you have compiled the changes you can check this via command similar to the following:

  pvs -dsv -N SUNW_1.23 /usr/lib/libc.so.1 \
    | sed -n '1,/SUNW.*:/p' | egrep '((v?errx?)|(v?warnx?));'
                vwarnx;
                ...
    

  If you're adding private (underscored) symbols do not forget to add them to the SUNWprivate section. This is usually the case because the strong symbols are accompanied by weak symbols. Weak symbols go to the global part of the most recent SUNW section and strong symbols go to global part of SUNWprivate section.
• update libc's lint library
  If you are adding private symbols then add them as well. See the entries _vwarnfp et al. for example.
  After you're done it's time to run nightly with lint checks and fix the noise. (see below)
• Add per-symbol filters
  If you are moving stuff from a library to libc you will probably want to preserve the existing interfaces. To accomplish this per-symbol filters can be added to the library you're moving from. So, if symbol foo is moved from libbar to libc then change the line in the global section of libbar's mapfile to look like this:

  foo = FUNCTION FILTER libc.so.1;
  

  This was done with the *fp functions in libipsecutils' mapfile. The specialty in that case was that the *fp functions were renamed to underscored variants while moving them via redefines in errfp.h.
• Fix build/lint noise introduced by the changes
  There could be the following noises:
  • build noise
    Can be caused by symbol type clash (there is symbol of the same name defined in libc as FUNC and in $SRC/cmd as OBJT) which is not harmful because ld(1) will do due diligence and prefer the non-libc symbol. This can be fixed by renaming the local symbol. There could also be #define clash caused by inclusion of c_synonyms.h. Fixed via renaming as well.
  • lint noise
    In the 3rd pass of the lint checks an inconsistency in function declarations can be found such as this:

    /builds/.../usr/include/err.h", line 43: warning: function argument declared
    inconsistently: warn(arg 1) in utils.c(62) char * and llib-lc:err.h(43) const char *
    (E_INCONS_ARG_DECL2)
    

    The problem with this output is that there are cca 23 files named utils.c in ONNV. CR 6585621 is waiting someone to provide remedy for that via adding -F flag to LINTFLAGS in $SRC/lib and $SRC/cmd.
    After the right file(s) are found the fix is usually renaming again. Where the renaming is not possible -erroff=E_FUNC_DECL_VAR_ARG2 can be passed to lint(1).
• Make sure there are not duplicate symbols in libc after the changes
  This is necessary because it might confuse debugging tools (mdb, dtrace). For err/warn stuff there was one such occurence:

  [6583] | 301316| 37|FUNC |GLOB |0 |13 |_warnx
  [1925] | 320000| 96|FUNC |LOCL |0 |13 |_warnx
  

  This can be usually solved by renaming the local variant.
• Test thoroughly
  
  • test with different compilers
    SunStudio does different things than gcc so it is good idea to test the code with both.
  • Try to compile different consolidations (e.g. Companion CD, SFW) on top of the changes. For err/warn project a bug was filed to get RPM build fixed.
  • Test if the WEAK symbols actually work
    
  • Test the programs in ONNV affected by the changes
    e.g. the programs which needed to be modified because of the build/lint noise.
• Produce annotated putback list explaining the changes
  This is handy for a CRT advocate and saves time.
• If the change requires some sort of action from fellow gatelings, send a heads-up, e.g. like heads-up for err/warn.
• If you are actually adding code to libc (this includes moving code from other libraries to libc) send an e-mail similar to the heads-up e-mail to opensolaris-code mailing list, e.g. like this message about err/warn.

I do not get to meet customers very often but I clearly remember the last time where I participated in a pseudo-technical session with a new customer. The engineers were keen on learning details about all features which make Solaris outstanding but they were also bewildered by the lack of common functions such as daemon() (see CR 4471189). Yes, there is a number of private implementations in various places in ONNV, however this is not very useful. Until recently, this was also the case of err/warn function family.

With the putback of CR 6495220 there are now the following functions living in libc:

  void err(int, const char *, ...);
  void verr(int, const char *, va_list);
  void errx(int, const char *, ...);
  void verrx(int, const char *, va_list);
  void warn(const char *, ...);
  void vwarn(const char *, va_list);
  void warnx(const char *, ...);
  void vwarnx(const char *, va_list);

These functions were present in BSD systems for a long time (they've been in FreeBSD since 1994). The configure scripts of various pieces of software contain checks for presence and functionality of the err/warn functions in libc (and setting the HAVE_ERR_H define). For Solaris, those checks have now become enabled too.

The err(3C) man page covering these functions will be delivered in the same build as the changes, that is build 72.

The change is covered by PSARC 2006/662 architectural review and the stability level for all the functions is Committed (see Architecture Process and Tools for more details on how this works). Unfortunately, the case is still closed. Hopefully it will be opened soon.
Update 09-28-2007: the PSARC/2006/662 case is now open, including onepager document and e-mail discussion. Thanks to John Plocher, Darren Reed and Bill Sommerfeld.

As I prompted in the err/warn Heads-up there is now time to stop creating new private implementations and to look at purging duplicates (there are many of them, however not all can be gotten rid of in favour of err/warn from libc).

I will write about how to get code into libc in general from a more detailed perspective next time.

However, this does not mean there is nothing left to do in this area. Specifically, FreeBSD's err(3) contains functions err_set_exit(), err_set_file() and errc(), warnc(), verrc() and vwarnc(). These functions could be ported over too. Also, there is __progname or getprogname(3). Moreover, careful (code) reader has realized that err.c contains private implementations of functions with fp suffix. This function (sub)family could be made Committed too. So, there is still lot of work which could be done. Anyone is free to work on any of these. (see Jayakara Kini's blog entry on how to become OpenSolaris contributor if you're not already)