fdwalk should return 0 on an empty directory
[kopensolaris-gnu/glibc.git] / NOTES.opensolaris
index d86f517..7b77b6f 100644 (file)
@@ -1,3 +1,9 @@
+compiling:
+
+  Both glibc and sun's libc require 64-bit atomic operations, first found in
+  the Pentium Pro. The suggested method of compiling on 32-bit x86 is to set
+  CC='gcc -march=i586'.
+
 headers:
 
   In order to avoid duplicating OpenSolaris-specifc headers, most extensions
@@ -14,7 +20,8 @@ auxiliary vector (auxv_t):
   executables and libaries get an auxv_t while statically-linked executables
   don't. This means that statically-linked executables won't see PT_TLS, which
   is needed for __thread support. We can test for the SHARED macro for libc
-  library code, but in general, __thread will not work.
+  library code, but in general, __thread will not work for statically-linked
+  executables.
 
   In order to fix this, it should be a matter of changing the kernel to
   unconditionally supply the auxv_t.
@@ -30,6 +37,22 @@ scheduling:
   a class id with a posix scheduler (i.e. SCHED_*). The only exception is
   SCHED_SYS, which is guaranteed to have cid == 0.
 
+  The following schedulers are defined:
+
+  SCHED_*       | Name  | Min Prio  | Max Prio  |
+  -----------------------------------------------
+  SCHED_OTHER   | TS    | -60       | 60        |
+  SCHED_FIFO    | RT    | 0         | 59        |
+  SCHED_RR      | RT    | 0         | 59        |
+  SCHED_SYS     | SYS   | 60        | 99        |
+  SCHED_IA      | IA    | -60       | 60        |
+  SCHED_FSS     | FSS   | -60       | 60        |
+  SCHED_FX      | FX    | 0         | 60        |
+
+  Internally the maximum and minimum are stored in a short int. Further, for
+  mutexes, the ceiling is stored in a uint8_t. This means that it can be
+  assumed that priorities must be between -128 and 127.
+
 privileges:
 
   Each process has a set of privileges, represented by a prpriv_t. This struct
@@ -79,8 +102,8 @@ mutex:
 
     mutex_owner (32-bits): The lwpid of the owning thread.
 
-    mutex_cond (32-bits): An in-use counter that is incremented when waiting on
-      a condition and decremented when we return (or are cancelled).
+    mutex_cond_waiters (32-bits): An in-use counter that is incremented when
+      waiting on a condition and decremented when we return (or are cancelled).
 
   The kernel only touches the data field when it is cleared during cleanup for
   certain mutex types.
@@ -90,6 +113,9 @@ mutex:
   The kernel does not set mutex_lockbyte for mutexes with the
   LOCK_PRIO_INHERIT bit set.
 
+  The kernel does not use data.flag2. We use this to track the current priority
+  ceiling (mutex_real_ceiling) for LOCK_PRIO_PROTECT mutexes.
+
 semaphore:
 
 condition variable:
@@ -115,11 +141,58 @@ reader-writer lock:
   private implementation that used the embedded mutex and cv's would also work
   correctly in the shared case.
 
-  Our implementation adds three additional fields are included for tracking
-  the owner (thread and process) of a reader-writer lock.
+  Our implementation adds three additional fields for tracking the owner (thread
+  and process) of a reader-writer lock.
 
 [0] http://docs.sun.com/app/docs/doc/819-2243/rwlock-init-3c?a=view
 
+nsswitch:
+
+  nss_search
+
+    This is used to search a database given a key. Examples that use nss_search
+    include gethostbyname_r and _getauthattr.
+
+  nss_getent
+  nss_setent
+  nss_endent
+  nss_delete
+
+    These are used when for iterating over a database. nss_getent, nss_sent,
+    and nss_endent are used in gethostent, sethostent, and endhostent,
+    respectively. nss_delete is used to free resources used by the interation;
+    it usually directly follows a call to nss_endent.
+
+  _nss_XbyY_fgets
+
+    This function is used to parse a file directly, rather than going through
+    nsswitch.conf and its databases.
+
+syscalls:
+
+  Dealing with 64-bit returns in 32-bit code is tricky. For 32-bit x86, %eax
+  and %edx are not saved across function calls. Since syscalls always return
+  a 32-bit integer we always have to push/pop %eax across functions. However,
+  since there are very few 64-bit returning syscalls, we don't save %edx unless
+  we have a 64-bit returning syscall. The following is a list of 64-bit
+  returning syscalls:
+
+    getgid, getuid, getpid, forkx, pipe, lseek64
+
+  Currently, the only time we actually call functions is in the case of
+  cancellation points (we call pthread_async_enable/disable). lseek64 is the
+  only syscall listed above that is a cancellation point. To deal with this,
+  we define SYSCALL_64BIT_RETURN in lseek64.S, which triggers inclusion of
+  %edx saving.
+
+  Additionally, 64-bit returning syscalls set both %eax and %edx to -1 on
+  error. Similarily this behaviour is enabled by SYSCALL_64BIT_RETURN. Note
+  that getegid, geteuid, and getppid are special in that their libc
+  equivalents actually return 32-bit integers so we don't need to worry about
+  %edx on error. With forkx and pipe, it suffices to check only the lower
+  32-bits (one of the pid/fd's returned) for -1. For lseek64 we do have to
+  check the full 64-bit return for -1.
+
 sysconf:
 
   Many of the _SC_ sysconf values are obtained via the systemconf syscall. The
@@ -167,3 +240,9 @@ sysconf:
     _SC_CPUID_MAX           _CONFIG_CPUID_MAX
     _SC_EPHID_MAX           _CONFIG_EPHID_MAX
     _SC_SYMLOOP_MAX         _CONFIG_SYMLOOP_MAX         SYMLOOP_MAX
+
+fgetattr, fsetattr, getattrat, setattrat:
+
+  The *attr calls are new to OpenSolaris  and are similar to Linux's extended
+  attributes functions. They are implemented as openat(fd, attr_name, O_XATTR)
+  and then read/written via the respective syscall.