fdwalk should return 0 on an empty directory
[kopensolaris-gnu/glibc.git] / NOTES.opensolaris
1 compiling:
2
3   Both glibc and sun's libc require 64-bit atomic operations, first found in
4   the Pentium Pro. The suggested method of compiling on 32-bit x86 is to set
5   CC='gcc -march=i586'.
6
7 headers:
8
9   In order to avoid duplicating OpenSolaris-specifc headers, most extensions
10   define any constants/structs in accompanying private/"P" headers. For
11   example, zone_* is implemented in zone.c and constants/structs are defined in
12   zoneP.h.
13
14 auxiliary vector (auxv_t):
15
16   Proper OpenSolaris does not support statically-linked executables (i.e. via
17   gcc -static). However, glibc does, but with certain restrictions. The kernel
18   only builds the auxv_t if the elf file is not of type ET_EXEC or if the
19   PT_INTERP program header exists. This means that dynamically-linked
20   executables and libaries get an auxv_t while statically-linked executables
21   don't. This means that statically-linked executables won't see PT_TLS, which
22   is needed for __thread support. We can test for the SHARED macro for libc
23   library code, but in general, __thread will not work for statically-linked
24   executables.
25
26   In order to fix this, it should be a matter of changing the kernel to
27   unconditionally supply the auxv_t.
28
29 scheduling:
30
31   The OpenSolaris kernel allows for loadable schedule classes. A scheduling
32   class has an id (pc_cid), associated name (pc_clname), and class-specific
33   scheduling information. As new schedulers are loaded, they are incrementally
34   assigned new id's.
35
36   Since id's are assigned dynamically, there is no way to statically associate
37   a class id with a posix scheduler (i.e. SCHED_*). The only exception is
38   SCHED_SYS, which is guaranteed to have cid == 0.
39
40   The following schedulers are defined:
41
42   SCHED_*       | Name  | Min Prio  | Max Prio  |
43   -----------------------------------------------
44   SCHED_OTHER   | TS    | -60       | 60        |
45   SCHED_FIFO    | RT    | 0         | 59        |
46   SCHED_RR      | RT    | 0         | 59        |
47   SCHED_SYS     | SYS   | 60        | 99        |
48   SCHED_IA      | IA    | -60       | 60        |
49   SCHED_FSS     | FSS   | -60       | 60        |
50   SCHED_FX      | FX    | 0         | 60        |
51
52   Internally the maximum and minimum are stored in a short int. Further, for
53   mutexes, the ceiling is stored in a uint8_t. This means that it can be
54   assumed that priorities must be between -128 and 127.
55
56 privileges:
57
58   Each process has a set of privileges, represented by a prpriv_t. This struct
59   contains a header, followed by a number of priv_chunk_t blocks (the priv
60   sets), and finally followed by a number of priv_info_t blocks (per process
61   additional info).
62
63 threads:
64
65   The sun libpthread/libthread implementation assumes a 1:1 mapping between
66   pthread_t/thread_t and lwpid_t, while NPTL maps thread descriptors to
67   pthread_t. This behaviour was added to NPTL and maybe enabled by defining
68   PTHREAD_T_IS_TID.
69
70 mutex:
71
72   Recursive locks are represented by an 8-byte counter defined by the
73   mutex_rcount macro. The maximum number of recursive waiters is
74   UCHAR_MAX (255).
75
76   Various fields are defined in a 64-bit field. 32 of the bits are used to
77   hold the owner pid. 8-bits each are used for holding the lock byte, the
78   number of waiters, and the number of spinners. Solaris defines some macros
79   for accessing these (architecture dependent of course):
80
81     mutex_lockword (32-bits): This is used if only the lock bit needs to
82       touched.
83
84     mutex_lockword64 (64-bits): This is used if you need to atomically swap
85       both the lock bytes and the owner pid. Note that where the pid portion
86       is located is dependent on byte ordering.
87
88     mutex_lockbyte (8-bits): This is the actual lock byte. It is set to 1 when
89       the lock is locked, and 0 when unlocked.
90
91     mutex_waiters (8-bits): This is set to 1 when there is another thread
92       waiting and 0 when there are no other waiters.
93
94     mutex_spinners (8-bits): This byte is apparently unused.
95
96     mutex_ownerpid (32-bits): Set to the mutex owner's process pid when the
97       mutex is shared.
98
99   The data field (aka mutex_owner) is used by sun libc to store a pointer to
100   the thread-descriptor of the owning thread. We split this 64-bit field into
101   two fields:
102
103     mutex_owner (32-bits): The lwpid of the owning thread.
104
105     mutex_cond_waiters (32-bits): An in-use counter that is incremented when
106       waiting on a condition and decremented when we return (or are cancelled).
107
108   The kernel only touches the data field when it is cleared during cleanup for
109   certain mutex types.
110
111   The kernel does not handle recursive or error-checking mutexes.
112
113   The kernel does not set mutex_lockbyte for mutexes with the
114   LOCK_PRIO_INHERIT bit set.
115
116   The kernel does not use data.flag2. We use this to track the current priority
117   ceiling (mutex_real_ceiling) for LOCK_PRIO_PROTECT mutexes.
118
119 semaphore:
120
121 condition variable:
122
123   The cond_waiters_kernel byte is set to 1 if there are waiters on the
124   condition variable and 0 otherwise. The cond_waiters_user byte is not
125   used by the kernel.
126
127   The only clock types supported by sun libc are CLOCK_REALTIME and
128   CLOCK_HIGHRES.
129
130   The data field is not used by the kernel.
131
132 reader-writer lock:
133
134   The kernel only supports shared/process reader-writer locks; the private
135   rwlock implementation must be completely implemented in libc. For the shared
136   case, readercv and writercv are used to track the owner (thread and process).
137   The sun docs also state that the sun implementation favours writers over
138   readers[0].
139
140   There is no apparent advantage in using the rwlock syscalls since any
141   private implementation that used the embedded mutex and cv's would also work
142   correctly in the shared case.
143
144   Our implementation adds three additional fields for tracking the owner (thread
145   and process) of a reader-writer lock.
146
147 [0] http://docs.sun.com/app/docs/doc/819-2243/rwlock-init-3c?a=view
148
149 nsswitch:
150
151   nss_search
152
153     This is used to search a database given a key. Examples that use nss_search
154     include gethostbyname_r and _getauthattr.
155
156   nss_getent
157   nss_setent
158   nss_endent
159   nss_delete
160
161     These are used when for iterating over a database. nss_getent, nss_sent,
162     and nss_endent are used in gethostent, sethostent, and endhostent,
163     respectively. nss_delete is used to free resources used by the interation;
164     it usually directly follows a call to nss_endent.
165
166   _nss_XbyY_fgets
167
168     This function is used to parse a file directly, rather than going through
169     nsswitch.conf and its databases.
170
171 syscalls:
172
173   Dealing with 64-bit returns in 32-bit code is tricky. For 32-bit x86, %eax
174   and %edx are not saved across function calls. Since syscalls always return
175   a 32-bit integer we always have to push/pop %eax across functions. However,
176   since there are very few 64-bit returning syscalls, we don't save %edx unless
177   we have a 64-bit returning syscall. The following is a list of 64-bit
178   returning syscalls:
179
180     getgid, getuid, getpid, forkx, pipe, lseek64
181
182   Currently, the only time we actually call functions is in the case of
183   cancellation points (we call pthread_async_enable/disable). lseek64 is the
184   only syscall listed above that is a cancellation point. To deal with this,
185   we define SYSCALL_64BIT_RETURN in lseek64.S, which triggers inclusion of
186   %edx saving.
187
188   Additionally, 64-bit returning syscalls set both %eax and %edx to -1 on
189   error. Similarily this behaviour is enabled by SYSCALL_64BIT_RETURN. Note
190   that getegid, geteuid, and getppid are special in that their libc
191   equivalents actually return 32-bit integers so we don't need to worry about
192   %edx on error. With forkx and pipe, it suffices to check only the lower
193   32-bits (one of the pid/fd's returned) for -1. For lseek64 we do have to
194   check the full 64-bit return for -1.
195
196 sysconf:
197
198   Many of the _SC_ sysconf values are obtained via the systemconf syscall. The
199   following is a table of mappings from _SC_ to _CONFIG_ values. The third
200   column lists the value returned by sysdeps/posix/sysconf.c.
201
202     _SC_CHILD_MAX           _CONFIG_CHILD_MAX           _get_child_max
203     _SC_CLK_TCK             _CONFIG_CLK_TCK             _getclktck
204     _SC_NGROUPS_MAX         _CONFIG_NGROUPS             NGROUPS_MAX
205     _SC_OPEN_MAX            _CONFIG_OPEN_FILES          __getdtablesize
206     _SC_PAGESIZE            _CONFIG_PAGESIZE            __getpagesize
207     _SC_XOPEN_VERSION       _CONFIG_XOPEN_VER           _XOPEN_VERSION
208     _SC_STREAM_MAX          _CONFIG_OPEN_FILES          STREAM_MAX
209     _SC_NPROCESSORS_CONF    _CONFIG_NPROC_CONF          __get_nprocs_conf
210     _SC_NPROCESSORS_ONLN    _CONFIG_NPROC_ONLN          __get_nprocs
211     _SC_NPROCESSORS_MAX     _CONFIG_NPROC_MAX
212     _SC_STACK_PROT          _CONFIG_STACK_PROT
213     _SC_AIO_LISTIO_MAX      _CONFIG_AIO_LISTIO_MAX      AIO_LISTIO_MAX
214     _SC_AIO_MAX             _CONFIG_AIO_MAX             AIO_MAX
215     _SC_AIO_PRIO_DELTA_MAX  _CONFIG_AIO_PRIO_DELTA_MAX  AIO_PRIO_DELTA_MAX
216     _SC_DELAYTIMER_MAX      _CONFIG_DELAYTIMER_MAX      DELAYTIMER_MAX
217     _SC_MQ_OPEN_MAX         _CONFIG_MQ_OPEN_MAX         MQ_OPEN_MAX
218     _SC_MQ_PRIO_MAX         _CONFIG_MQ_PRIO_MAX         MQ_PRIO_MAX
219     _SC_RTSIG_MAX           _CONFIG_RTSIG_MAX           RTSIG_MAX
220     _SC_SEM_NSEMS_MAX       _CONFIG_SEM_NSEMS_MAX       SEM_NSEMS_MAX
221     _SC_SEM_VALUE_MAX       _CONFIG_SEM_VALUE_MAX       SEM_VALUE_MAX
222     _SC_SIGQUEUE_MAX        _CONFIG_SIGQUEUE_MAX        SIGQUEUE_MAX
223     _SC_SIGRT_MAX           _CONFIG_SIGRT_MAX
224     _SC_SIGRT_MIN           _CONFIG_SIGRT_MIN
225     _SC_TIMER_MAX           _CONFIG_TIMER_MAX           TIMER_MAX
226     _SC_PHYS_PAGES          _CONFIG_PHYS_PAGES          __get_phys_pages
227     _SC_AVPHYS_PAGES        _CONFIG_AVPHYS_PAGES        __get_avphys_pages
228     _SC_COHER_BLKSZ         _CONFIG_COHERENCY
229     _SC_SPLIT_CACHE         _CONFIG_SPLIT_CACHE
230     _SC_ICACHE_SZ           _CONFIG_ICACHESZ
231     _SC_DCACHE_SZ           _CONFIG_DCACHESZ
232     _SC_ICACHE_LINESZ       _CONFIG_ICACHELINESZ
233     _SC_DCACHE_LINESZ       _CONFIG_DCACHELINESZ
234     _SC_ICACHE_BLKSZ        _CONFIG_ICACHEBLKSZ
235     _SC_DCACHE_BLKSZ        _CONFIG_DCACHEBLKSZ
236     _SC_DCACHE_TBLKSZ       _CONFIG_DCACHETBLKSZ
237     _SC_ICACHE_ASSOC        _CONFIG_ICACHE_ASSOC
238     _SC_DCACHE_ASSOC        _CONFIG_DCACHE_ASSOC
239     _SC_MAXPID              _CONFIG_MAXPID
240     _SC_CPUID_MAX           _CONFIG_CPUID_MAX
241     _SC_EPHID_MAX           _CONFIG_EPHID_MAX
242     _SC_SYMLOOP_MAX         _CONFIG_SYMLOOP_MAX         SYMLOOP_MAX
243
244 fgetattr, fsetattr, getattrat, setattrat:
245
246   The *attr calls are new to OpenSolaris  and are similar to Linux's extended
247   attributes functions. They are implemented as openat(fd, attr_name, O_XATTR)
248   and then read/written via the respective syscall.