fdwalk should return 0 on an empty directory
[kopensolaris-gnu/glibc.git] / NOTES.opensolaris
index 9a420f1..7b77b6f 100644 (file)
@@ -1,3 +1,16 @@
+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
+  define any constants/structs in accompanying private/"P" headers. For
+  example, zone_* is implemented in zone.c and constants/structs are defined in
+  zoneP.h.
+
 auxiliary vector (auxv_t):
 
   Proper OpenSolaris does not support statically-linked executables (i.e. via
 auxiliary vector (auxv_t):
 
   Proper OpenSolaris does not support statically-linked executables (i.e. via
@@ -7,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
   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.
 
   In order to fix this, it should be a matter of changing the kernel to
   unconditionally supply the auxv_t.
@@ -23,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.
 
   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
 privileges:
 
   Each process has a set of privileges, represented by a prpriv_t. This struct
@@ -72,8 +102,8 @@ mutex:
 
     mutex_owner (32-bits): The lwpid of the owning thread.
 
 
     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.
 
   The kernel only touches the data field when it is cleared during cleanup for
   certain mutex types.
@@ -83,6 +113,9 @@ mutex:
   The kernel does not set mutex_lockbyte for mutexes with the
   LOCK_PRIO_INHERIT bit set.
 
   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:
 semaphore:
 
 condition variable:
@@ -108,11 +141,58 @@ reader-writer lock:
   private implementation that used the embedded mutex and cv's would also work
   correctly in the shared case.
 
   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
 
 
 [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
 sysconf:
 
   Many of the _SC_ sysconf values are obtained via the systemconf syscall. The
@@ -160,3 +240,9 @@ sysconf:
     _SC_CPUID_MAX           _CONFIG_CPUID_MAX
     _SC_EPHID_MAX           _CONFIG_EPHID_MAX
     _SC_SYMLOOP_MAX         _CONFIG_SYMLOOP_MAX         SYMLOOP_MAX
     _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.