diff options
Diffstat (limited to 'winsup/doc')
37 files changed, 7963 insertions, 0 deletions
diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in new file mode 100644 index 000000000..74c0be821 --- /dev/null +++ b/winsup/doc/Makefile.in @@ -0,0 +1,91 @@ +# -*- Makefile -*- for winsup/doc +# Copyright (c) 1998-2000 Cygnus Solutions. +# +# This file is part of Cygwin. +# +# This software is a copyrighted work licensed under the terms of the +# Cygwin license. Please consult the file "CYGWIN_LICENSE" for +# details. + +SHELL = @SHELL@ +srcdir = @srcdir@ +VPATH = @srcdir@ + +DOC=faq.txt faq.info readme.txt readme.info +HTMLDOC=faq.html readme.html + +CC:=@CC@ +CC_FOR_TARGET:=@CC@ +exeext:=@build_exeext@ + +MAKEINFO:=makeinfo +TEXI2DVI:=texi2dvi +TEXI2HTML:=texi2html + +include $(srcdir)/../Makefile.common + +TOCLEAN:=faq.txt *.html readme.txt doctool.o doctool \ + cygwin-ug.sgml cygwin-ug-net.sgml + +.SUFFIXES: + +# You can add cygwin-api/cygwin-api.html if you want to. +all : \ + cygwin-ug/cygwin-ug.html \ + cygwin-ug-net/cygwin-ug-net.html \ + cygwin-api-int/cygwin-api-int.html \ + $(DOC) \ + $(HTMLDOC) + +clean: + rm -f $(TOCLEAN) + +install: all + +cygwin-ug/cygwin-ug.html : cygwin-ug.sgml doctool + -db2html $< + +cygwin-ug.sgml : cygwin-ug.in.sgml ./doctool Makefile + -./doctool -m -d $(srcdir) -d $(utils_source) -s $(srcdir) -o $@ $< + +cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.sgml doctool + -db2html $< + +cygwin-ug-net.sgml : cygwin-ug-net.in.sgml ./doctool Makefile + -./doctool -m -d $(srcdir) -d $(utils_source) -s $(srcdir) -o $@ $< + +cygwin-api/cygwin-api.html : cygwin-api.sgml + -db2html $< + +cygwin-api.sgml : cygwin-api.in.sgml ./doctool Makefile + -./doctool -m -d $(srcdir) -d $(utils_source) -s $(srcdir) -o $@ $< + +cygwin-api-int/cygwin-api-int.html : cygwin-api-int.sgml + -db2html $< + +cygwin-api-int.sgml : cygwin-api.in.sgml ./doctool Makefile + -./doctool -i -m -d $(srcdir) -d $(utils_source) -s $(srcdir) -b cygwin-api-int -o $@ $< + +./doctool : doctool.c + gcc -g $< -o $@ + +%.info: %.texinfo + -$(MAKEINFO) -I$(srcdir) $< + +%.txt: %.texinfo + -$(MAKEINFO) -I$(srcdir) $< + +%.html: %.texinfo + -$(TEXI2HTML) -I$(srcdir) $< + +readme.txt: readme.texinfo + -$(MAKEINFO) -I$(srcdir) --no-split --no-headers $< -o - |\ + sed '/^Concept Index/,$$d' > $@ + +faq.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo + -for i in $(srcdir)/*.texinfo ; do \ + sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \ + -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \ + $(TEXI2HTML) -split_chapter -v ./faq.texinfo; \ + rm -f *.texinfo; \ + cp faq_toc.html faq.html diff --git a/winsup/doc/calls.texinfo b/winsup/doc/calls.texinfo new file mode 100644 index 000000000..970efddfd --- /dev/null +++ b/winsup/doc/calls.texinfo @@ -0,0 +1,686 @@ +@chapter What Unix API calls are supported by Cygwin? + +This is the beginning of documentation listing the calls supported +by the Cygwin library. + +All POSIX.1/1996 and ANSI C calls are listed in this file. Note that +while almost all POSIX.1/1990 calls are included in Cygwin, most +POSIX.1/1996 calls are not (yet at least!). Additional Unix +compatibility calls and extended libc/libm calls are provided by +Cygwin but may or may not be listed yet. + +To see if a function is implemented but not listed here, check for the +presence of the call in the file winsup/cygwin.din in the sources. In +addition, you may want to read the source code corresponding to the call +to verify that it is not a stub. Finally, libc/libm functions +(including extended calls not listed here) may be documented in the +newlib texinfo documentation. + +Calls are implemented on both Windows 95 and NT unless otherwise +noted. Included are references to relevant standards, if any. +Calls starting with "cygwin_" are Cygwin-specific calls. + +@section ANSI C Library Functions + +@itemize @code + +@item libc stdio (newlib/libc/stdio) +@itemize @code +@item clearerr: C 4.9.10.1 +@item fclose: C 4.9.5.1, P 8.2.3.2 +@item feof: C 4.9.10.2 +@item ferror: C 4.9.10.3 +@item fflush: C 4.9.5.2, P 8.2.3.4 +@item fgetc: C 4.9.7.1, P 8.2.3.5 +@item fgetpos: C 4.9.9.1 +@item fgets: C 4.9.7.2, P 8.2.3.5 +@item fopen: C 4.9.5.3, P 8.2.3.1 +@item fprintf: C 4.9.7.3, P 8.2.3.6 +@item fputc: C 4.9.7.3, P 8.2.3.6 +@item fputs: C 4.9.7.4, P 8.2.3.6 +@item fread: C 4.9.8.1, P 8.2.3.5 +@item freopen: C 4.9.5.4, P 8.2.3.3 +@item fscanf: C 4.9.6.2, P 8.2.3.7 +@item fseek: C 4.9.9.2, P 8.2.3.7 +@item fsetpos: C 4.9.9.3 +@item ftell: C 4.9.9.4, P 8.2.3.10 +@item fwrite: C 4.9.8.2, P 8.2.3.6 +@item getc: C 4.9.7.5, P 8.2.3.5 +@item getchar: C 4.9.7.6, P 8.2.3.5 +@item gets: C 4.9.7.7, P 8.2.3.5 +@item perror: C 4.9.10.4, P 8.2.3.8 +@item printf: C 4.9.6.3, P 8.2.3.6 +@item putc: C 4.9.7.8, P 8.2.3.6 +@item putchar: C 4.9.7.9, P 8.2.3.6 +@item puts: C 4.9.7.10, P 8.2.3.6 +@item remove: C 4.9.4.1, P 8.2.4 +@item rename: C 4.9.4.2, P 5.5.3.1 +@item rewind: C 4.9.9.5, P 8.2.3.7 +@item scanf: C 4.9.6.4, P 8.2.3.5 +@item setbuf: C 4.9.5.5 +@item setvbuf: C 4.9.5.6 +@item sprintf: C 4.9.6.5 +@item sscanf: C 4.9.6.6 +@item tmpfile: C 4.9.4.3, P 8.2.3.9 +@item tmpnam: C 4.9.4.4, P 8.2.5 +@item vfprintf: C 4.9.6.7 +@item ungetc: C 4.9.7.11 +@item vprintf: C 4.9.6.8 +@item vsprintf: C 4.9.6.9 +@end itemize + +@item libc string (newlib/libc/string) +@itemize @code +@item memchr: C 4.11.5.1 +@item memcmp: C 4.11.4.1 +@item memcpy: C 4.11.2.1 +@item memmove: C 4.11.2.2 +@item memset: C 4.11.6.1 +@item strcat: C 4.11.3.1 +@item strchr: C 4.11.5.2 +@item strcmp: C 4.11.4.2 +@item strcoll: C 4.11.4.3 +@item strcpy: C 4.11.2.3 +@item strcspn: C 4.11.5.3 +@item strerror: C 4.11.6.2 +@item strlen: C 4.11.6.3 +@item strncat: C 4.11.3.2 +@item strncmp: C 4.11.3.2 +@item strncpy: C 4.11.2.4 +@item strpbrk: C 4.11.5.4 +@item strrchr: C 4.11.5.5 +@item strspn: C 4.11.5.6 +@item strstr: C 4.11.5.7 +@item strtok: C 4.11.5.8 +@item strxfrm: C 4.11.4.5 +@end itemize + +@item libc stdlib (newlib/libc/stdlib, environ.cc, newlib/libc/include/machine/setjmp.h newlib/libc/include/assert.h) +@itemize @code +@item abort: C 4.10.4.1, P 8.2.3.12 +@item abs: C 4.10.6.1 +@item assert: C 4.2.1.1 +@item atexit: C 4.10.4.2 +@item atof: C 4.10.1.1 +@item atoi: C 4.10.1.2 +@item atol: C 4.10.1.3 +@item bsearch: C 4.10.5.1 +@item calloc: C 4.10.3.1 +@item div: C 4.10.6.2 +@item exit: C 4.10.4.3, P 8.2.3.12 +@item free: C 4.10.3.2 +@item getenv: C 4.10.4.4, P 4.6.1.1 +@item labs: C 4.10.6.3 +@item ldiv: C 4.10.6.2 +@item longjmp: C 4.6.2.1 +@item malloc: C 4.10.3.3 +@item mblen: C 4.10.7.1 +@item mbstowcs: C 4.10.8.1 +@item mbtowc: C 4.10.7.2 +@item qsort: 4.10.5.2 +@item rand: C 4.10.2.1 +@item realloc: C 4.10.3.4 +@item setjmp: C 4.6.1.1 +@item srand: C 4.10.2.2 +@item strtod: C 4.10.1.4 +@item strtol: C 4.10.1.5 +@item strtoul: C 4.10.1.6 +@item system: C 4.10.4.5 +@item wcstombs: C 4.10.8.2 +@item wctomb: C 4.10.7.3 +@end itemize + +@item libc time (times.cc, newlib/libc/time) +@itemize @code +@item asctime: C 4.12.3.1 +@item gmtime: C 4.12.3.3 +@item localtime: C 4.12.3.4, P 8.1.1 +@item time: C 4.12.2.4, P 4.5.1.1 +@item clock: C 4.12.2.1 +@item ctime: C 4.12.3.2 +@item difftime: C 4.12.2.2 +@item mktime: C 4.12.2.3, P 8.1.1 +@item strftime: C 4.11.6.2 +@end itemize + +@item libc signals (signal.cc, newlib/libc/signal) +@itemize @code +@item raise: C 4.7.2.1 +@item signal: C 4.7.1.1 +@end itemize + +@item libc ctype (newlib/libc/ctype) +@itemize @code +@item isalnum: C 4.3.1.1 +@item isalpha: C 4.3.1.2 +@item iscntrl: C 4.3.1.3 +@item isdigit: C 4.3.1.4 +@item isgraph: C 4.3.1.5 +@item islower: C 4.3.1.6 +@item isprint: C 4.3.1.7 +@item ispunct: C 4.3.1.8 +@item isspace: C 4.3.1.9 +@item isupper: C 4.3.1.10 +@item isxdigit: C 4.3.1.11 +@item tolower: C 4.3.2.1 +@item toupper: C 4.3.2.2 +@end itemize + +@item libm math (newlib/libm/math) +@itemize @code +@item acos: C 4.5.2.1 +@item asin: C 4.5.2.2 +@item atan: C 4.5.2.3 +@item atan2: C 4.5.2.4 +@item ceil: C 4.5.6.1 +@item cos: C 4.5.2.5 +@item cosh: C 4.5.3.2 +@item exp: C 4.5.4.1 +@item fabs: C 4.5.6.2 +@item floor: C 4.5.6.3 +@item fmod: C 4.5.6.4 +@item frexp: C 4.5.4.2 +@item ldexp: C 4.5.4.3 +@item log: C 4.5.4.4 +@item log10: C 4.5.4.5 +@item modf: C 4.5.4.6 +@item pow: C 4.5.5.1 +@item sin: C 4.5.2.6 +@item sinh: C 4.5.3.2 +@item sqrt: C 4.5.5.2 +@item tan: C 4.5.2.7 +@item tanh: C 4.5.3.3 +@end itemize + +@item libc misc (newlib/libc/locale, gcc/ginclude/stdarg.h) +@itemize @code +@item localeconv: C 4.4.2.1 +@item setlocale: C 4.4.1.1, P 8.1.2.1 +@item va_arg: C 4.8.1.2 +@item va_end: C 4.8.1.3 +@item va_start: C 4.8.1.1 +@end itemize + +@section POSIX.1/96 Functions + +@item Process Primitives (Section 3) +@itemize @code +@item fork: P 3.1.1.1 +@item execl: P 3.1.2.1 +@item execle: P 3.1.2.1 +@item execlp: P 3.1.2.1 +@item execv: P 3.1.2.1 +@item execve: P 3.1.2.1 +@item execvp: P 3.1.2.1 +@item pthread_atfork: P96 3.1.3.1 -- unimplemented +@item wait: P 3.2.1.1 +@item waitpid: P 3.2.1.1 +@item _exit: P 3.2.2.1 +@item kill: P 3.3.2.1 +@item sigemptyset: P 3.3.3.1 +@item sigfillset: P 3.3.3.1 +@item sigaddset: P 3.3.3.1 +@item sigdelset: P 3.3.3.1 +@item sigismember: P 3.3.3.1 +@item sigaction: P 3.3.4.1 +@item pthread_sigmask: P96 3.3.5.1 +@item sigprocmask: P 3.3.5.1 +@item sigpending: P 3.3.6.1 +@item sigsuspend: P 3.3.7.1 +@item sigwait: P96 3.3.8.1 -- unimplemented +@item sigwaitinfo: P96 3.3.8.1 -- unimplemented +@item sigtimedwait: P96 3.3.8.1 -- unimplemented +@item sigqueue: P96 3.3.9.1 -- unimplemented +@item pthread_kill: P96 3.3.10.1 +@item alarm: P 3.4.1.1 +@item pause: P 3.4.2.1 +@item sleep: P 3.4.3.1 +@end itemize + +@item Process Environment (Section 4) +@itemize @code +@item getpid: P 4.1.1.1 +@item getppid: P 4.1.1.1 +@item getuid: P 4.2.1.1 +@item geteuid: P 4.2.1.1 +@item getgid: P 4.2.1.1 +@item getegid: P 4.2.1.1 +@item setuid: P 4.2.2.1 (stub, sets ENOSYS, returns zero) +@item setgid: P 4.2.2.1 (stub, sets ENOSYS, returns zero) +@item getgroups: P 4.2.3.1 +@item getlogin: P 4.2.4.1 +@item getlogin_r: P 4.2.4.1 -- unimplemented +@item getpgrp: P 4.3.1.1 +@item setsid: P 4.3.2.1 +@item setpgid: P 4.3.3.1 +@item uname: P 4.4.1.1 +@item time: C 4.12.2.4, P 4.5.1.1 +@item times: P 4.5.2.1 +@item getenv: C 4.10.4.4, P 4.6.1.1 +@item ctermid: P 4.7.1.1 +@item ttyname: P 4.7.2.1 +@item ttyname_r: P 4.7.2.1 -- unimplemented +@item isatty: P 4.7.2.1 +@item sysconf: P 4.8.1.1 +@end itemize + +@item Files and Directories (Section 5) +@itemize @code +@item opendir: P 5.1.2.1 +@item readdir: P 5.1.2.1 +@item readdir_r: P96 5.1.2.1 -- unimplemented +@item rewinddir: P 5.1.2.1 +@item closedir: P 5.1.2.1 +@item chdir: P 5.2.1.1 +@item getcwd: P 5.2.2.1 +@item open: P 5.3.1.1 +@item creat: P 5.3.2.1 +@item umask: P 5.3.3.1 +@item link: P 5.3.4.1 (copy file in Win 95, and when link fails in NT) +@item mkdir: P 5.4.1.1 +@item mkfifo: P 5.4.2.1 -- unimplemented!!! +@item unlink: P 5.5.1.1 +@item rmdir: P 5.5.2.1 +@item rename: C 4.9.4.2, P 5.5.3.1 +@item stat: P 5.6.2.1 +@item fstat: P 5.6.2.1 +@item access: P 5.6.3.1 +@item chmod: P 5.6.4.1 +@item fchmod: P96 5.6.4.1 +@item chown: P 5.6.5.1 (stub in Win 95; always returns zero) +@item utime: P 5.6.6.1 +@item ftruncate: P96 5.6.7.1 +@item pathconf: P 5.7.1.1 +@item fpathconf: P 5.7.1.1 +@end itemize + +@item Input and Output Primitives (Section 6) +@itemize @code +@item pipe: P 6.1.1.1 +@item dup: P 6.2.1.1 +@item dup2: P 6.2.1.1 +@item close: P 6.3.1.1 +@item read: P 6.4.1.1 +@item write: P 6.4.2.1 +@item fcntl: P 6.5.2.1 (note: fcntl(fd, F_GETLK,...) is not implemented (returns -1 with errno set to ENOSYS)). +@item lseek: P 6.5.3.1 (note: only works correctly on binary files) +@item fsync: P96 6.6.1.1 +@item fdatasync: P96 6.6.2.1 -- unimplemented +@item aio_read: P96 6.7.2.1 -- unimplemented +@item aio_write: P96 6.7.3.1 -- unimplemented +@item lio_listio: P96 6.7.4.1 -- unimplemented +@item aio_error: P96 6.7.5.1 -- unimplemented +@item aio_return: P96 6.7.6.1 -- unimplemented +@item aio_cancel: P96 6.7.7.1 -- unimplemented +@item aio_suspend: P96 6.7.8.1 -- unimplemented +@item aio_fsync: P96 6.7.9.1 -- unimplemented +@end itemize + +@item Device- and Class-Specific Functions (Section 7) +@itemize @code +@item cfgetispeed: P96 7.1.3.1 +@item cfgetospeed: P96 7.1.3.1 +@item cfsetispeed: P96 7.1.3.1 +@item cfsetospeed: P96 7.1.3.1 +@item tcdrain: P 7.2.2.1 +@item tcflow: P 7.2.2.1 +@item tcflush: P 7.2.2.1 +@item tcgetattr: P96 7.2.1.1 +@item tcgetpgrp: P 7.2.3.1 +@item tcsendbreak: P 7.2.2.1 +@item tcsetattr: P96 7.2.1.1 +@item tcsetpgrp: P 7.2.4.1 +@end itemize + +@item Language-Specific Services for the C Programming Language +(Section 8) +@itemize @code +@item abort: C 4.10.4.1, P 8.2.3.12 +@item asctime_r: P96 8.3.4.1 -- unimplemented +@item ctime_r: P96 8.3.5.1 -- unimplemented +@item exit: C 4.10.4.3, P 8.2.3.12 +@item fclose: C 4.9.5.1, P 8.2.3.2 +@item fdopen: P 8.2.2.1 +@item fflush: C 4.9.5.2, P 8.2.3.4 +@item fgetc: C 4.9.7.1, P 8.2.3.5 +@item fgets: C 4.9.7.2, P 8.2.3.5 +@item fileno: P 8.2.1.1 +@item flockfile: P96 8.2.6.1 -- unimplemented +@item fopen: C 4.9.5.3, P 8.2.3.1 +@item fprintf: C 4.9.7.3, P 8.2.3.6 +@item fputc: C 4.9.7.3, P 8.2.3.6 +@item fputs: C 4.9.7.4, P 8.2.3.6 +@item fread: C 4.9.8.1, P 8.2.3.5 +@item freopen: C 4.9.5.4, P 8.2.3.3 +@item fscanf: C 4.9.6.2, P 8.2.3.7 +@item fseek: C 4.9.9.2, P 8.2.3.7 +@item ftell: C 4.9.9.4, P 8.2.3.10 +@item ftrylockfile: P96 8.2.6.1 -- unimplemented +@item funlockfile: P96 8.2.6.1 -- unimplemented +@item fwrite: C 4.9.8.2, P 8.2.3.6 +@item getc: C 4.9.7.5, P 8.2.3.5 +@item getc_unlocked: P96 8.2.7.1 -- unimplemented +@item getchar: C 4.9.7.6, P 8.2.3.5 +@item getchar_unlocked: P96 8.2.7.1 -- unimplemented +@item gets: C 4.9.7.7, P 8.2.3.5 +@item gmtime_r: P96 8.3.6.1 -- unimplemented +@item localtime_r: P96 8.3.7.1 -- unimplemented +@item perror: C 4.9.10.4, P 8.2.3.8 +@item printf: C 4.9.6.3, P 8.2.3.6 +@item putc: C 4.9.7.8, P 8.2.3.6 +@item putc_unlocked: P96 8.2.7.1 -- unimplemented +@item putchar: C 4.9.7.9, P 8.2.3.6 +@item putchar_unlocked: P96 8.2.7.1 -- unimplemented +@item puts: C 4.9.7.10, P 8.2.3.6 +@item rand_r: P96 8.3.8.1 -- unimplemented +@item remove: C 4.9.4.1, P 8.2.4 +@item rewind: C 4.9.9.5, P 8.2.3.7 +@item scanf: C 4.9.6.4, P 8.2.3.5 +@item setlocale: C 4.4.1.1, P 8.1.2.1 +@item siglongjmp: P 8.3.1.1 +@item sigsetjmp: P 8.3.1.1 +@item strtok_r: P96 8.3.3.1 -- unimplemented +@item tmpfile: C 4.9.4.3, P 8.2.3.9 +@item tmpnam: C 4.9.4.4, P 8.2.5 +@item tzset: P 8.3.2.1 +@end itemize + +@item System Databases (Section 9) +@itemize @code +@item getgrgid: P 9.2.1.1 +@item getgrgid_r: P96 9.2.1.1 -- unimplemented +@item getgrnam: P 9.2.1.1 +@item getgrnam_r: P96 9.2.1.1 -- unimplemented +@item getpwnam: P 9.2.2.1 +@item getpwnam_r: P96 9.2.2.1 -- unimplemented +@item getpwuid: P 9.2.2.1 +@item getpwuid_r: P96 9.2.2.1 -- unimplemented +@end itemize + +@item Synchronization (Section 11) +@itemize @code +@item pthread_cond_broadcast: P96 11.4.3.1 -- unimplemented +@item pthread_cond_destroy: P96 11.4.2.1 -- unimplemented +@item pthread_cond_init: P96 11.4.2.1 -- unimplemented +@item pthread_cond_signal: P96 11.4.3.1 -- unimplemented +@item pthread_cond_timedwait: P96 11.4.4.1 -- unimplemented +@item pthread_cond_wait: P96 11.4.4.1 -- unimplemented +@item pthread_condattr_destroy: P96 11.4.1.1 -- unimplemented +@item pthread_condattr_getpshared: P96 11.4.1.1 -- unimplemented +@item pthread_condattr_init: P96 11.4.1.1 -- unimplemented +@item pthread_condattr_setpshared: P96 11.4.1.1 -- unimplemented +@item pthread_mutex_destroy: P96 11.3.2.1 +@item pthread_mutex_init: P96 11.3.2.1 +@item pthread_mutex_lock: P96 11.3.3.1 +@item pthread_mutex_trylock: P96 11.3.3.1 +@item pthread_mutex_unlock: P96 11.3.3.1 +@item sem_close: P96 11.2.4.1 -- unimplemented +@item sem_destroy: P96 11.2.2.1 +@item sem_getvalue: P96 11.2.8.1 -- unimplemented +@item sem_init: P96 11.2.1.1 +@item sem_open: P96 11.2.3.1 -- unimplemented +@item sem_post: P96 11.2.7.1 +@item sem_trywait: P96 11.2.6.1 +@item sem_unlink: P96 11.2.5.1 -- unimplemented +@item sem_wait: P96 11.2.6.1 +@end itemize + +@item Memory Management (Section 12) +@itemize @code +@item mlock: P96 12.1.2.1 -- unimplemented +@item mlockall: P96 12.1.1.1 -- unimplemented +@item mmap: P96 12.2.1.1 +@item mprotect: P96 12.2.3.1 +@item msync: P96 12.2.4.1 +@item munlock: P96 12.1.2.1 -- unimplemented +@item munlockall: P96 12.1.1.1 -- unimplemented +@item munmap: P96 12.2.2.1 +@item shm_open: P96 12.3.1.1 -- unimplemented +@item shm_unlink: P96 12.3.2.1 -- unimplemented +@end itemize + +@item Execution Scheduling (Section 13) +@itemize @code +@item pthread_attr_getinheritsched: P96 13.5.1.1 -- unimplemented +@item pthread_attr_getschedparam: P96 13.5.1.1 -- unimplemented +@item pthread_attr_getschedpolicy: P96 13.5.1.1 -- unimplemented +@item pthread_attr_getscope: P96 13.5.1.1 -- unimplemented +@item pthread_attr_setinheritsched: P96 13.5.1.1 -- unimplemented +@item pthread_attr_setschedparam: P96 13.5.1.1 -- unimplemented +@item pthread_attr_setschedpolicy: P96 13.5.1.1 -- unimplemented +@item pthread_attr_setscope: P96 13.5.1.1 -- unimplemented +@item pthread_getschedparam: P96 13.5.2.1 -- unimplemented +@item pthread_mutex_getprioceiling: P96 13.6.2.1 -- unimplemented +@item pthread_mutex_setprioceiling: P96 13.6.2.1 -- unimplemented +@item pthread_mutexattr_getprioceiling: P96 13.6.1.1 -- unimplemented +@item pthread_mutexattr_getprotocol: P96 13.6.1.1 -- unimplemented +@item pthread_mutexattr_setprioceiling: P96 13.6.1.1 -- unimplemented +@item pthread_mutexattr_setprotocol: P96 13.6.1.1 -- unimplemented +@item pthread_setschedparam: P96 13.5.2.1 -- unimplemented +@item sched_get_priority_max: P96 13.3.6.1 -- unimplemented +@item sched_get_priority_min: P96 13.3.6.1 -- unimplemented +@item sched_getparam: P96 13.3.2.1 -- unimplemented +@item sched_getscheduler: P96 13.3.4.1 -- unimplemented +@item sched_rr_get_interval: P96 13.3.6.1 -- unimplemented +@item sched_setparam: P96 13.3.1.1 -- unimplemented +@item sched_setscheduler: P96 13.3.3.1 -- unimplemented +@item sched_yield: P96 13.3.5.1 -- unimplemented +@end itemize + +@item Clocks and Timers (Section 14) +@itemize @code +@item clock_getres: P96 14.2.1.1 -- unimplemented +@item clock_gettime: P96 14.2.1.1 -- unimplemented +@item clock_settime: P96 14.2.1.1 -- unimplemented +@item nanosleep: P96 14.2.5.1 -- unimplemented +@item timer_create: P96 14.2.2.1 -- unimplemented +@item timer_delete: P96 14.2.3.1 -- unimplemented +@item timer_getoverrun: P96 14.2.4.1 -- unimplemented +@item timer_gettime: P96 14.2.4.1 -- unimplemented +@item timer_settime: P96 14.2.4.1 -- unimplemented +@end itemize + +@item Message Passing (Section 15) +@itemize @code +@item mq_close: P96 15.2.2.1 -- unimplemented +@item mq_getattr: P96 15.2.8.1 -- unimplemented +@item mq_notify: P96 15.2.6.1 -- unimplemented +@item mq_open: P96 15.2.1.1 -- unimplemented +@item mq_receive: P96 15.2.5.1 -- unimplemented +@item mq_send: P96 15.2.4.1 -- unimplemented +@item mq_setattr: P96 15.2.7.1 -- unimplemented +@item mq_unlink: P96 15.2.3.1 -- unimplemented +@end itemize + +@item Thread Management (Section 16) +@itemize @code +@item pthread_attr_destroy: P96 16.2.1.1 +@item pthread_attr_getdetachstate: P96 16.2.1.1 -- unimplemented +@item pthread_attr_getstackaddr: P96 16.2.1.1 -- unimplemented +@item pthread_attr_getstacksize: P96 16.2.1.1 +@item pthread_attr_init: P96 16.2.1.1 +@item pthread_attr_setdetachstate: P96 16.2.1.1 -- unimplemented +@item pthread_attr_setstackaddr: P96 16.2.1.1 -- unimplemented +@item pthread_attr_setstacksize: P96 16.2.1.1 +@item pthread_create: P96 16.2.2.1 +@item pthread_detach: P96 16.2.4.1 -- unimplemented +@item pthread_equal: P96 16.2.7.1 +@item pthread_exit: P96 16.2.5.1 +@item pthread_join: P96 16.2.3.1 -- unimplemented +@item pthread_once: P96 16.2.8.1 -- unimplemented +@item pthread_self: P96 16.2.6.1 +@end itemize + +@item Thread-Specific Data (Section 17) +@itemize @code +@item pthread_getspecific: P96 17.1.2.1 +@item pthread_key_create: P96 17.1.1.1 +@item pthread_key_delete: P96 17.1.3.1 +@item pthread_setspecific: P96 17.1.2.1 +@end itemize + +@item Thread Cancellation (Section 18) +@itemize @code +@item pthread_cancel: P96 18.2.1.1 -- unimplemented +@item pthread_cleanup_pop: P96 18.2.3.1 -- unimplemented +@item pthread_cleanup_push: P96 18.2.3.1 -- unimplemented +@item pthread_setcancelstate: P96 18.2.2.1 -- unimplemented +@item pthread_setcanceltype: P96 18.2.2.1 -- unimplemented +@item pthread_testcancel: P96 18.2.2.1 -- unimplemented +@end itemize + +@section Misc Functions + +@item Networking (net.cc) (Standardized by POSIX 1.g, which is probably still in draft?) +@itemize @code +@item accept +@item bind +@item connect +@item getdomainname +@item gethostbyaddr +@item gethostbyname +@item getpeername +@item getprotobyname +@item getprotobynumber +@item getservbyname +@item getservbyport +@item getsockname +@item getsockopt +@item herror +@item htonl +@item htons +@item inet_addr +@item inet_makeaddr +@item inet_netof +@item inet_ntoa +@item listen +@item ntohl +@item ntohs +@item rcmd +@item recv +@item recvfrom +@item rexec +@item rresvport +@item send +@item sendto +@item setsockopt +@item shutdown +@item socket +@item socketpair +@end itemize + +Of these networking calls, rexec, rcmd and rresvport are implemented +in MS IP stack but may not be implemented in other vendors' stacks. + +@item Other +@itemize @code +@item chroot (stub, sets ENOSYS, returns -1) +@item closelog +@item cwait +@item cygwin_conv_to_full_posix_path +@item cygwin_conv_to_full_win32_path +@item cygwin_conv_to_posix_path +@item cygwin_conv_to_win32_path +@item cygwin_posix_path_list_p +@item cygwin_posix_to_win32_path_list +@item cygwin_posix_to_win32_path_list_buf_size +@item cygwin_split_path +@item cygwin_win32_to_posix_path_list +@item cygwin_win32_to_posix_path_list_buf_size +@item cygwin_winpid_to_pid +@item dlclose +@item dlerror +@item dlfork +@item dlopen +@item dlsym +@item endgrent +@item endhostent +@item ffs +@item fstatfs +@item ftime +@item get_osfhandle +@item getdtablesize +@item getgrent +@item gethostname +@item getitimer +@item getmntent +@item getpagesize +@item getpgid +@item getpwent +@item gettimeofday: BSD +@item grantpt +@item initgroups (stub) +@item ioctl +@item killpg +@item login +@item logout +@item lstat +@item mknod (stub, sets ENOSYS, returns -1) +@item memccpy +@item nice +@item openlog +@item pclose +@item popen +@item ptsname +@item putenv +@item random +@item readv +@item realpath +@item regfree +@item rexec +@item select +@item setegid: SVR4 (stub, sets ENOSYS, returns zero)@item endpwent +@item setenv +@item seterrno +@item seteuid (stub, sets ENOSYS, returns zero) +@item sethostent +@item setitimer +@item setmntent +@item setmode +@item setpassent +@item setpgrp +@item setpwent +@item settimeofday: BSD (stub, set ENOSYS, return -1) +@item sexecl +@item sexecle +@item sexeclp +@item sexeclpe +@item sexeclpe +@item sexecp +@item sexecv +@item sexecve +@item sexecvpe +@item sigpause +@item spawnl (spawn calls are from Windows C library) +@item spawnle +@item spawnlp +@item spawnlpe +@item spawnv +@item spawnve +@item spawnvp +@item spawnvpe +@item srandom +@item statfs +@item strsignal +@item strtosigno +@item swab +@item syslog +@item timezone +@item truncate (SVR4/4.3+BSD) +@item ttyslot +@item unlockpt +@item unsetenv +@item usleep +@item utimes +@item vfork: stub that calls fork +@item vhangup (stub, sets ENOSYS, returns -1) +@item wait3 +@item wait4 +@item wcscmp +@item wcslen +@item wprintf +@item writev +@end itemize + +@end itemize + diff --git a/winsup/doc/changes.texinfo b/winsup/doc/changes.texinfo new file mode 100644 index 000000000..6e464784d --- /dev/null +++ b/winsup/doc/changes.texinfo @@ -0,0 +1,202 @@ +@section Release Beta 20.1 (Dec 4 1998) + +This is a bug fix update to the Beta 20 release. + +The main change is an improved version of the Cygwin library although +there are also a couple of other minor changes to the tools. + +@subsection Changes in specific tools: + +The "-mno-cygwin" flag to gcc now include the correct headers. In 20.0, +it included the Cygwin headers which was incorrect. + +The "-pipe" flag to gcc works correctly now. + +The cygcheck program now reassures users that not finding cpp is the +correct behavior. + +The "-b" flag to md5sum can now be used to generate correct checksums +of binary files. + +The libtermcap library has been added to the compiler tools sources. +It is the new source of the termcap library and /etc/termcap file. + +The less pager (using libtermcap) has been added to the binary +distribution. + +@subsection Changes in the Cygwin API (cygwin.dll): + +This version of Cygwin is backwards-compatible with the beta 20 and 19 +releases. The library is now much more stable under Windows 9x and the +bugs affecting configures under 9x (and NT to a lesser extent) have +also been fixed. + +The bug that made it necessary to start the value of the CYGWIN +environment variable with two leading spaces has been fixed. + +The serial support in the select call has been fixed. + +Handling of DLLs loaded by non-cygwin apps has been improved. Bugs in +dlopen have been fixed. + +Passing _SC_CHILD_MAX to the sysconf function now yields CHILD_MAX (63) +instead of _POSIX_CHILD_MAX (3). + +Several minor path bugs have been fixed. Including the one that +caused "mkdir a/" to fail. + +The include file sys/sysmacros.h has been added. Added missing protos +for wcslen and wcscmp to wchar.h. + +__P is now defined in include/sys/cdefs.h. To support that last change, +the top-level Makefile.in now sets CC_FOR_TARGET and CXX_FOR_TARGET +differently. + +Cygwin now exports the following newlib bessel functions: j1, jn, y1, +yn. + +Several tty ioctl options have been added: TCGETA, TCSETA, TCSETAW, and +TCSETAF. + +Several functions cope with NULL pointer references more gracefully. + +Problems with execution of relative paths via #! should be fixed. + +@section Release Beta 20 (Oct 30 1998) + +This is a significant update to the Beta 19 release. In addition to an +EGCS-based compiler and updated tools, this release includes a new +version of the Cygwin library that contains many improvements and +bugfixes over the last one. + +@subsection The project has a new name! + +Starting with this release, we are retiring the "GNU-Win32" name for the +releases. We have also dropped the "32" from Cygwin32. This means that +you should now refer to the tools as "the Cygwin toolset", the library +as "the Cygwin library" or "the Cygwin DLL", and the library's interface +as "the Cygwin API". + +Because of this name change, we have changed any aspects of the library +that involved the name "Cygwin32". For example, the CYGWIN32 +environment variable is now the CYGWIN environment variable. API +functions starting with cygwin32_ are still available under that form +for backwards-compatibility as well as under the new cygwin_-prefixed +names. The same goes for the change of preprocessor define from +__CYGWIN32__ to __CYGWIN__. We will remove the old names in a future +release so please take the minute or two that it will take to remove +those "32"s. Thanks and I apologize for the hassle this may cause +people. We would have changed the name to "Bob" but that name's already +taken by Microsoft... :-) + +Why change it? For one thing, not all of the software included in the +distributions is GNU software, including the Cygwin library itself. So +calling the project "GNU-Win32" has always been a bit of a misnomer. In +addition, we think that calling the tools the "Cygwin tools" that use +the "Cygwin library" will be less confusing to people. + +Also notice that we are now on the spiffy new sourceware.cygnus.com +web/ftp site. The old address will work for some unknown period of +time (hopefully at least until we get all of the mirrors adjusted). + +@subsection Changes in specific tools: + +The latest public EGCS release is now the basis for the compiler used +in Cygwin distributions. As a result, EGCS 1.1 is the compiler in this +release, with a few additional x86/Cygwin-related patches. + +Those of you who are more interested in native Windows development than +in porting Unix programs will be glad to know that a new gcc flag +"-mno-cygwin" will link in the latest Mingw32 libs and produce an +executable that does not use Cygwin. + +All of the other development tools have been updated to their latest +versions. The linker (ld) includes many important bug fixes. It is now +possible to safely strip a DLL with a .reloc section. The windres +resource compiler is significantly improved. + +Beta 20 also includes upgrades to a number of packages: ash-0.3.2-4, +bash 2.02.1, grep-2.2, ncurses 4.2, and less 332. We have added bzip2 +0.9.0 to the distribution. And you'll now find that the df utility +has joined its other friends from the fileutils package. + +The sh executable is still ash from the Debian Linux distribution but no +longer has the problematic quoting bug that was present in the Beta 19 +release. Control-Cs in the bash shell no longer kill background tasks. + +Tcl/tk are upgraded to version 8.1a2 (with additional patches). +Compatible versions of tix and itcl are included. These all include +Cygwin-compatible configury files so you can do a Unix-style build of +the Win32 ports of tcl/tk. expect has been upgraded to 5.26 with some +additional Cygwin patches. + +In response to customer requests and feedback, Cygnus has developed a +better graphical front end to GDB than GDBtk or WinGDB. This tcl-based +GUI is shipping today to customers of the GNUPro Toolkit. The +instrumentation changes to GDB and the tcl interpreter that was built +into GDB are part of the GPL'd source base. But the tcl scripts are not +being made available to the net at this time. For this reason, you will +only find a command-line version of gdb in this Cygwin release. + +DJ Delorie has written a new "cygcheck" program that will print out +useful information about how your Cygwin environment is set up, what +DLLs a named executable is loading from where, etc. We hope this will +make it easier to help diagnose common setup problems. + +The ps utility has been upgraded. It now has several options including +shorter and longer output formats. + +@subsection Changes in the Cygwin API (cygwin.dll): + +This version of Cygwin is backwards-compatible with the beta 19 release. +You can use the new "cygwin1.dll" with your old B19-compiled executables +if you move the old "cygwinb19.dll" out of the way and install a copy +of "cygwin1.dll" as "cygwinb19.dll". + +Quite a lot of the Cygwin internals have been rewritten or modified to +address various issues. If you have a question about specific changes, +the winsup/ChangeLog file in the development tools sources lists all +changes made to the DLL over the last three years. Following are a few +highlights: + +We are now using a new versioning scheme for Cygwin. There is now a +separate version number for the DLL, the API, the shared memory region +interfaces, and the registry interface. This will hopefully make it +easier for multiple Cygwin toolsets to coexist in one user environment. + +Windows 98 is now supported (it is like Windows 95 from Cygwin's +perspective). We still recommend upgrading to Windows NT. + +While there is still a lot left to do in improving Cygwin's runtime +performance, we have put some effort into this prior to the B20 release. +Hopefully you will find that the latest version of Cygwin is faster than +ever. In addition, we have plugged several nasty handle leaks +associated with opening/closing files and with using ttys. + +The lseek call now uses WriteFile to fill gaps with zeros whenever a +write is done past an EOF, rather than leaving "undefined" data as Win32 +specifies. + +Significant work has been done to improve the Cygwin header files. + +The Cygwin Support for Unix-style serial I/O is much improved. + +Path handling has had another round of fixes/rewrites. We no longer use +NT Extended Attributes by default for storing Unix permissions/execute +status because the file NT creates on FAT partitions is not scalable to +thousands of files (everything slows to a crawl). + +Signal handling has also gotten a fair amount of attention. +Unfortunately, there are still some problems combining itimers and +Windows 9x. + +The number of ttys has been upped from 16 to 128. + +New API calls included in the DLL: sethostent, endhostent. + +As mentioned earlier, all cygwin32_-prefixed functions are now exported +with a cygwin_ prefix instead. Please adjust your code to call the +newly named functions. + +reads of `slow' devices are now correctly interrupted by signals, i.e. +a read will receive an EINTR. diff --git a/winsup/doc/configure b/winsup/doc/configure new file mode 100755 index 000000000..09d5a070c --- /dev/null +++ b/winsup/doc/configure @@ -0,0 +1,1078 @@ +#! /bin/sh + +# Guess values for system-dependent variables and create Makefiles. +# Generated automatically using autoconf version 2.13 +# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. +# +# This configure script is free software; the Free Software Foundation +# gives unlimited permission to copy, distribute and modify it. + +# Defaults: +ac_help= +ac_default_prefix=/usr/local +# Any additions from configure.in: + +# Initialize some variables set by options. +# The variables have the same names as the options, with +# dashes changed to underlines. +build=NONE +cache_file=./config.cache +exec_prefix=NONE +host=NONE +no_create= +nonopt=NONE +no_recursion= +prefix=NONE +program_prefix=NONE +program_suffix=NONE +program_transform_name=s,x,x, +silent= +site= +sitefile= +srcdir= +target=NONE +verbose= +x_includes=NONE +x_libraries=NONE +bindir='${exec_prefix}/bin' +sbindir='${exec_prefix}/sbin' +libexecdir='${exec_prefix}/libexec' +datadir='${prefix}/share' +sysconfdir='${prefix}/etc' +sharedstatedir='${prefix}/com' +localstatedir='${prefix}/var' +libdir='${exec_prefix}/lib' +includedir='${prefix}/include' +oldincludedir='/usr/include' +infodir='${prefix}/info' +mandir='${prefix}/man' + +# Initialize some other variables. +subdirs= +MFLAGS= MAKEFLAGS= +SHELL=${CONFIG_SHELL-/bin/sh} +# Maximum number of lines to put in a shell here document. +ac_max_here_lines=12 + +ac_prev= +for ac_option +do + + # If the previous option needs an argument, assign it. + if test -n "$ac_prev"; then + eval "$ac_prev=\$ac_option" + ac_prev= + continue + fi + + case "$ac_option" in + -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; + *) ac_optarg= ;; + esac + + # Accept the important Cygnus configure options, so we can diagnose typos. + + case "$ac_option" in + + -bindir | --bindir | --bindi | --bind | --bin | --bi) + ac_prev=bindir ;; + -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) + bindir="$ac_optarg" ;; + + -build | --build | --buil | --bui | --bu) + ac_prev=build ;; + -build=* | --build=* | --buil=* | --bui=* | --bu=*) + build="$ac_optarg" ;; + + -cache-file | --cache-file | --cache-fil | --cache-fi \ + | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) + ac_prev=cache_file ;; + -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ + | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) + cache_file="$ac_optarg" ;; + + -datadir | --datadir | --datadi | --datad | --data | --dat | --da) + ac_prev=datadir ;; + -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ + | --da=*) + datadir="$ac_optarg" ;; + + -disable-* | --disable-*) + ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then + { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + eval "enable_${ac_feature}=no" ;; + + -enable-* | --enable-*) + ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then + { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "enable_${ac_feature}='$ac_optarg'" ;; + + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ + | --exec | --exe | --ex) + ac_prev=exec_prefix ;; + -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ + | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ + | --exec=* | --exe=* | --ex=*) + exec_prefix="$ac_optarg" ;; + + -gas | --gas | --ga | --g) + # Obsolete; use --with-gas. + with_gas=yes ;; + + -help | --help | --hel | --he) + # Omit some internal or obsolete options to make the list less imposing. + # This message is too long to be a string in the A/UX 3.1 sh. + cat << EOF +Usage: configure [options] [host] +Options: [defaults in brackets after descriptions] +Configuration: + --cache-file=FILE cache test results in FILE + --help print this message + --no-create do not create output files + --quiet, --silent do not print \`checking...' messages + --site-file=FILE use FILE as the site file + --version print the version of autoconf that created configure +Directory and file names: + --prefix=PREFIX install architecture-independent files in PREFIX + [$ac_default_prefix] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX + [same as prefix] + --bindir=DIR user executables in DIR [EPREFIX/bin] + --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] + --libexecdir=DIR program executables in DIR [EPREFIX/libexec] + --datadir=DIR read-only architecture-independent data in DIR + [PREFIX/share] + --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] + --sharedstatedir=DIR modifiable architecture-independent data in DIR + [PREFIX/com] + --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] + --libdir=DIR object code libraries in DIR [EPREFIX/lib] + --includedir=DIR C header files in DIR [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] + --infodir=DIR info documentation in DIR [PREFIX/info] + --mandir=DIR man documentation in DIR [PREFIX/man] + --srcdir=DIR find the sources in DIR [configure dir or ..] + --program-prefix=PREFIX prepend PREFIX to installed program names + --program-suffix=SUFFIX append SUFFIX to installed program names + --program-transform-name=PROGRAM + run sed PROGRAM on installed program names +EOF + cat << EOF +Host type: + --build=BUILD configure for building on BUILD [BUILD=HOST] + --host=HOST configure for HOST [guessed] + --target=TARGET configure for TARGET [TARGET=HOST] +Features and packages: + --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] + --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) + --x-includes=DIR X include files are in DIR + --x-libraries=DIR X library files are in DIR +EOF + if test -n "$ac_help"; then + echo "--enable and --with options recognized:$ac_help" + fi + exit 0 ;; + + -host | --host | --hos | --ho) + ac_prev=host ;; + -host=* | --host=* | --hos=* | --ho=*) + host="$ac_optarg" ;; + + -includedir | --includedir | --includedi | --included | --include \ + | --includ | --inclu | --incl | --inc) + ac_prev=includedir ;; + -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ + | --includ=* | --inclu=* | --incl=* | --inc=*) + includedir="$ac_optarg" ;; + + -infodir | --infodir | --infodi | --infod | --info | --inf) + ac_prev=infodir ;; + -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) + infodir="$ac_optarg" ;; + + -libdir | --libdir | --libdi | --libd) + ac_prev=libdir ;; + -libdir=* | --libdir=* | --libdi=* | --libd=*) + libdir="$ac_optarg" ;; + + -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ + | --libexe | --libex | --libe) + ac_prev=libexecdir ;; + -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ + | --libexe=* | --libex=* | --libe=*) + libexecdir="$ac_optarg" ;; + + -localstatedir | --localstatedir | --localstatedi | --localstated \ + | --localstate | --localstat | --localsta | --localst \ + | --locals | --local | --loca | --loc | --lo) + ac_prev=localstatedir ;; + -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ + | --localstate=* | --localstat=* | --localsta=* | --localst=* \ + | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) + localstatedir="$ac_optarg" ;; + + -mandir | --mandir | --mandi | --mand | --man | --ma | --m) + ac_prev=mandir ;; + -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) + mandir="$ac_optarg" ;; + + -nfp | --nfp | --nf) + # Obsolete; use --without-fp. + with_fp=no ;; + + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) + no_create=yes ;; + + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) + no_recursion=yes ;; + + -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ + | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ + | --oldin | --oldi | --old | --ol | --o) + ac_prev=oldincludedir ;; + -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ + | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ + | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) + oldincludedir="$ac_optarg" ;; + + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) + ac_prev=prefix ;; + -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) + prefix="$ac_optarg" ;; + + -program-prefix | --program-prefix | --program-prefi | --program-pref \ + | --program-pre | --program-pr | --program-p) + ac_prev=program_prefix ;; + -program-prefix=* | --program-prefix=* | --program-prefi=* \ + | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) + program_prefix="$ac_optarg" ;; + + -program-suffix | --program-suffix | --program-suffi | --program-suff \ + | --program-suf | --program-su | --program-s) + ac_prev=program_suffix ;; + -program-suffix=* | --program-suffix=* | --program-suffi=* \ + | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) + program_suffix="$ac_optarg" ;; + + -program-transform-name | --program-transform-name \ + | --program-transform-nam | --program-transform-na \ + | --program-transform-n | --program-transform- \ + | --program-transform | --program-transfor \ + | --program-transfo | --program-transf \ + | --program-trans | --program-tran \ + | --progr-tra | --program-tr | --program-t) + ac_prev=program_transform_name ;; + -program-transform-name=* | --program-transform-name=* \ + | --program-transform-nam=* | --program-transform-na=* \ + | --program-transform-n=* | --program-transform-=* \ + | --program-transform=* | --program-transfor=* \ + | --program-transfo=* | --program-transf=* \ + | --program-trans=* | --program-tran=* \ + | --progr-tra=* | --program-tr=* | --program-t=*) + program_transform_name="$ac_optarg" ;; + + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + silent=yes ;; + + -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) + ac_prev=sbindir ;; + -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ + | --sbi=* | --sb=*) + sbindir="$ac_optarg" ;; + + -sharedstatedir | --sharedstatedir | --sharedstatedi \ + | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ + | --sharedst | --shareds | --shared | --share | --shar \ + | --sha | --sh) + ac_prev=sharedstatedir ;; + -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ + | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ + | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ + | --sha=* | --sh=*) + sharedstatedir="$ac_optarg" ;; + + -site | --site | --sit) + ac_prev=site ;; + -site=* | --site=* | --sit=*) + site="$ac_optarg" ;; + + -site-file | --site-file | --site-fil | --site-fi | --site-f) + ac_prev=sitefile ;; + -site-file=* | --site-file=* | --site-fil=* | --site-fi=* | --site-f=*) + sitefile="$ac_optarg" ;; + + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + srcdir="$ac_optarg" ;; + + -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ + | --syscon | --sysco | --sysc | --sys | --sy) + ac_prev=sysconfdir ;; + -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ + | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) + sysconfdir="$ac_optarg" ;; + + -target | --target | --targe | --targ | --tar | --ta | --t) + ac_prev=target ;; + -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) + target="$ac_optarg" ;; + + -v | -verbose | --verbose | --verbos | --verbo | --verb) + verbose=yes ;; + + -version | --version | --versio | --versi | --vers) + echo "configure generated by autoconf version 2.13" + exit 0 ;; + + -with-* | --with-*) + ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then + { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "with_${ac_package}='$ac_optarg'" ;; + + -without-* | --without-*) + ac_package=`echo $ac_option|sed -e 's/-*without-//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then + { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + eval "with_${ac_package}=no" ;; + + --x) + # Obsolete; use --with-x. + with_x=yes ;; + + -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ + | --x-incl | --x-inc | --x-in | --x-i) + ac_prev=x_includes ;; + -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ + | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) + x_includes="$ac_optarg" ;; + + -x-libraries | --x-libraries | --x-librarie | --x-librari \ + | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) + ac_prev=x_libraries ;; + -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries="$ac_optarg" ;; + + -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } + ;; + + *) + if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then + echo "configure: warning: $ac_option: invalid host type" 1>&2 + fi + if test "x$nonopt" != xNONE; then + { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } + fi + nonopt="$ac_option" + ;; + + esac +done + +if test -n "$ac_prev"; then + { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } +fi + +trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 + +# File descriptor usage: +# 0 standard input +# 1 file creation +# 2 errors and warnings +# 3 some systems may open it to /dev/tty +# 4 used on the Kubota Titan +# 6 checking for... messages and results +# 5 compiler messages saved in config.log +if test "$silent" = yes; then + exec 6>/dev/null +else + exec 6>&1 +fi +exec 5>./config.log + +echo "\ +This file contains any messages produced by compilers while +running configure, to aid debugging if configure makes a mistake. +" 1>&5 + +# Strip out --no-create and --no-recursion so they do not pile up. +# Also quote any args containing shell metacharacters. +ac_configure_args= +for ac_arg +do + case "$ac_arg" in + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) ;; + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; + *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) + ac_configure_args="$ac_configure_args '$ac_arg'" ;; + *) ac_configure_args="$ac_configure_args $ac_arg" ;; + esac +done + +# NLS nuisances. +# Only set these to C if already set. These must not be set unconditionally +# because not all systems understand e.g. LANG=C (notably SCO). +# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! +# Non-C LC_CTYPE values break the ctype check. +if test "${LANG+set}" = set; then LANG=C; export LANG; fi +if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi +if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi +if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi + +# confdefs.h avoids OS command line length limits that DEFS can exceed. +rm -rf conftest* confdefs.h +# AIX cpp loses on an empty file, so make sure it contains at least a newline. +echo > confdefs.h + +# A filename unique to this package, relative to the directory that +# configure is in, which we can look for to find out if srcdir is correct. +ac_unique_file=cygwin-api.in.sgml + +# Find the source files, if location was not specified. +if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then its parent. + ac_prog=$0 + ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` + test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. + srcdir=$ac_confdir + if test ! -r $srcdir/$ac_unique_file; then + srcdir=.. + fi +else + ac_srcdir_defaulted=no +fi +if test ! -r $srcdir/$ac_unique_file; then + if test "$ac_srcdir_defaulted" = yes; then + { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } + else + { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } + fi +fi +srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` + +# Prefer explicitly selected file to automatically selected ones. +if test -z "$sitefile"; then + if test -z "$CONFIG_SITE"; then + if test "x$prefix" != xNONE; then + CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" + else + CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" + fi + fi +else + CONFIG_SITE="$sitefile" +fi +for ac_site_file in $CONFIG_SITE; do + if test -r "$ac_site_file"; then + echo "loading site script $ac_site_file" + . "$ac_site_file" + fi +done + +if test -r "$cache_file"; then + echo "loading cache $cache_file" + . $cache_file +else + echo "creating cache $cache_file" + > $cache_file +fi + +ac_ext=c +# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. +ac_cpp='$CPP $CPPFLAGS' +ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' +ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' +cross_compiling=$ac_cv_prog_cc_cross + +ac_exeext= +ac_objext=o +if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then + # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. + if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then + ac_n= ac_c=' +' ac_t=' ' + else + ac_n=-n ac_c= ac_t= + fi +else + ac_n= ac_c='\c' ac_t= +fi + + + + + +ac_aux_dir= +for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do + if test -f $ac_dir/install-sh; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install-sh -c" + break + elif test -f $ac_dir/install.sh; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install.sh -c" + break + fi +done +if test -z "$ac_aux_dir"; then + { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; } +fi +ac_config_guess=$ac_aux_dir/config.guess +ac_config_sub=$ac_aux_dir/config.sub +ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. + + +# Do some error checking and defaulting for the host and target type. +# The inputs are: +# configure --host=HOST --target=TARGET --build=BUILD NONOPT +# +# The rules are: +# 1. You are not allowed to specify --host, --target, and nonopt at the +# same time. +# 2. Host defaults to nonopt. +# 3. If nonopt is not specified, then host defaults to the current host, +# as determined by config.guess. +# 4. Target and build default to nonopt. +# 5. If nonopt is not specified, then target and build default to host. + +# The aliases save the names the user supplied, while $host etc. +# will get canonicalized. +case $host---$target---$nonopt in +NONE---*---* | *---NONE---* | *---*---NONE) ;; +*) { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } ;; +esac + + +# Make sure we can run config.sub. +if ${CONFIG_SHELL-/bin/sh} $ac_config_sub sun4 >/dev/null 2>&1; then : +else { echo "configure: error: can not run $ac_config_sub" 1>&2; exit 1; } +fi + +echo $ac_n "checking host system type""... $ac_c" 1>&6 +echo "configure:586: checking host system type" >&5 + +host_alias=$host +case "$host_alias" in +NONE) + case $nonopt in + NONE) + if host_alias=`${CONFIG_SHELL-/bin/sh} $ac_config_guess`; then : + else { echo "configure: error: can not guess host type; you must specify one" 1>&2; exit 1; } + fi ;; + *) host_alias=$nonopt ;; + esac ;; +esac + +host=`${CONFIG_SHELL-/bin/sh} $ac_config_sub $host_alias` +host_cpu=`echo $host | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\1/'` +host_vendor=`echo $host | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\2/'` +host_os=`echo $host | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\3/'` +echo "$ac_t""$host" 1>&6 + +echo $ac_n "checking target system type""... $ac_c" 1>&6 +echo "configure:607: checking target system type" >&5 + +target_alias=$target +case "$target_alias" in +NONE) + case $nonopt in + NONE) target_alias=$host_alias ;; + *) target_alias=$nonopt ;; + esac ;; +esac + +target=`${CONFIG_SHELL-/bin/sh} $ac_config_sub $target_alias` +target_cpu=`echo $target | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\1/'` +target_vendor=`echo $target | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\2/'` +target_os=`echo $target | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\3/'` +echo "$ac_t""$target" 1>&6 + +echo $ac_n "checking build system type""... $ac_c" 1>&6 +echo "configure:625: checking build system type" >&5 + +build_alias=$build +case "$build_alias" in +NONE) + case $nonopt in + NONE) build_alias=$host_alias ;; + *) build_alias=$nonopt ;; + esac ;; +esac + +build=`${CONFIG_SHELL-/bin/sh} $ac_config_sub $build_alias` +build_cpu=`echo $build | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\1/'` +build_vendor=`echo $build | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\2/'` +build_os=`echo $build | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\3/'` +echo "$ac_t""$build" 1>&6 + +test "$host_alias" != "$target_alias" && + test "$program_prefix$program_suffix$program_transform_name" = \ + NONENONEs,x,x, && + program_prefix=${target_alias}- + + +if test $host != $build; then + ac_tool_prefix=${host_alias}- +else + ac_tool_prefix= +fi + +# Extract the first word of "${ac_tool_prefix}gcc", so it can be a program name with args. +set dummy ${ac_tool_prefix}gcc; ac_word=$2 +echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 +echo "configure:657: checking for $ac_word" >&5 +if eval "test \"`echo '$''{'ac_cv_prog_CC'+set}'`\" = set"; then + echo $ac_n "(cached) $ac_c" 1>&6 +else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" + ac_dummy="$PATH" + for ac_dir in $ac_dummy; do + test -z "$ac_dir" && ac_dir=. + if test -f $ac_dir/$ac_word; then + ac_cv_prog_CC="${ac_tool_prefix}gcc" + break + fi + done + IFS="$ac_save_ifs" +fi +fi +CC="$ac_cv_prog_CC" +if test -n "$CC"; then + echo "$ac_t""$CC" 1>&6 +else + echo "$ac_t""no" 1>&6 +fi + + +if test -z "$ac_cv_prog_CC"; then +if test -n "$ac_tool_prefix"; then + # Extract the first word of "gcc", so it can be a program name with args. +set dummy gcc; ac_word=$2 +echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 +echo "configure:689: checking for $ac_word" >&5 +if eval "test \"`echo '$''{'ac_cv_prog_CC'+set}'`\" = set"; then + echo $ac_n "(cached) $ac_c" 1>&6 +else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" + ac_dummy="$PATH" + for ac_dir in $ac_dummy; do + test -z "$ac_dir" && ac_dir=. + if test -f $ac_dir/$ac_word; then + ac_cv_prog_CC="gcc" + break + fi + done + IFS="$ac_save_ifs" + test -z "$ac_cv_prog_CC" && ac_cv_prog_CC="gcc" +fi +fi +CC="$ac_cv_prog_CC" +if test -n "$CC"; then + echo "$ac_t""$CC" 1>&6 +else + echo "$ac_t""no" 1>&6 +fi + +else + CC="gcc" +fi +fi + +if test -z "$CC"; then + # Extract the first word of "cc", so it can be a program name with args. +set dummy cc; ac_word=$2 +echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 +echo "configure:725: checking for $ac_word" >&5 +if eval "test \"`echo '$''{'ac_cv_prog_CC'+set}'`\" = set"; then + echo $ac_n "(cached) $ac_c" 1>&6 +else + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else + IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" + ac_prog_rejected=no + ac_dummy="$PATH" + for ac_dir in $ac_dummy; do + test -z "$ac_dir" && ac_dir=. + if test -f $ac_dir/$ac_word; then + if test "$ac_dir/$ac_word" = "/usr/ucb/cc"; then + ac_prog_rejected=yes + continue + fi + ac_cv_prog_CC="cc" + break + fi + done + IFS="$ac_save_ifs" +if test $ac_prog_rejected = yes; then + # We found a bogon in the path, so make sure we never use it. + set dummy $ac_cv_prog_CC + shift + if test $# -gt 0; then + # We chose a different compiler from the bogus one. + # However, it has the same basename, so the bogon will be chosen + # first if we set CC to just the basename; use the full file name. + shift + set dummy "$ac_dir/$ac_word" "$@" + shift + ac_cv_prog_CC="$@" + fi +fi +fi +fi +CC="$ac_cv_prog_CC" +if test -n "$CC"; then + echo "$ac_t""$CC" 1>&6 +else + echo "$ac_t""no" 1>&6 +fi + + test -z "$CC" && { echo "configure: error: no acceptable cc found in \$PATH" 1>&2; exit 1; } +fi + +if test $ac_cv_prog_gcc = yes; then + GCC=yes + ac_test_CFLAGS="${CFLAGS+set}" + ac_save_CFLAGS="$CFLAGS" + CFLAGS= + echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6 +echo "configure:779: checking whether ${CC-cc} accepts -g" >&5 +if eval "test \"`echo '$''{'ac_cv_prog_cc_g'+set}'`\" = set"; then + echo $ac_n "(cached) $ac_c" 1>&6 +else + echo 'void f(){}' > conftest.c +if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then + ac_cv_prog_cc_g=yes +else + ac_cv_prog_cc_g=no +fi +rm -f conftest* + +fi + +echo "$ac_t""$ac_cv_prog_cc_g" 1>&6 + if test "$ac_test_CFLAGS" = set; then + CFLAGS="$ac_save_CFLAGS" + elif test $ac_cv_prog_cc_g = yes; then + CFLAGS="-g -O2" + else + CFLAGS="-O2" + fi + if test "$ac_test_CXXFLAGS" != set; then + CXXFLAGS='$(CFLAGS)' + fi +else + GCC= + test "${CFLAGS+set}" = set || CFLAGS="-g" +fi + + + + +trap '' 1 2 15 +cat > confcache <<\EOF +# This file is a shell script that caches the results of configure +# tests run on this system so they can be shared between configure +# scripts and configure runs. It is not useful on other systems. +# If it contains results you don't want to keep, you may remove or edit it. +# +# By default, configure uses ./config.cache as the cache file, +# creating it if it does not exist already. You can give configure +# the --cache-file=FILE option to use a different cache file; that is +# what configure does when it calls configure scripts in +# subdirectories, so they share the cache. +# Giving --cache-file=/dev/null disables caching, for debugging configure. +# config.status only pays attention to the cache file if you give it the +# --recheck option to rerun configure. +# +EOF +# The following way of writing the cache mishandles newlines in values, +# but we know of no workaround that is simple, portable, and efficient. +# So, don't put newlines in cache variables' values. +# Ultrix sh set writes to stderr and can't be redirected directly, +# and sets the high bit in the cache file unless we assign to the vars. +(set) 2>&1 | + case `(ac_space=' '; set | grep ac_space) 2>&1` in + *ac_space=\ *) + # `set' does not quote correctly, so add quotes (double-quote substitution + # turns \\\\ into \\, and sed turns \\ into \). + sed -n \ + -e "s/'/'\\\\''/g" \ + -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" + ;; + *) + # `set' quotes correctly as required by POSIX, so do not add quotes. + sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' + ;; + esac >> confcache +if cmp -s $cache_file confcache; then + : +else + if test -w $cache_file; then + echo "updating cache $cache_file" + cat confcache > $cache_file + else + echo "not updating unwritable cache $cache_file" + fi +fi +rm -f confcache + +trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 + +test "x$prefix" = xNONE && prefix=$ac_default_prefix +# Let make expand exec_prefix. +test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' + +# Any assignment to VPATH causes Sun make to only execute +# the first set of double-colon rules, so remove it if not needed. +# If there is a colon in the path, we need to keep it. +if test "x$srcdir" = x.; then + ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' +fi + +trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 + +# Transform confdefs.h into DEFS. +# Protect against shell expansion while executing Makefile rules. +# Protect against Makefile macro expansion. +cat > conftest.defs <<\EOF +s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g +s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g +s%\[%\\&%g +s%\]%\\&%g +s%\$%$$%g +EOF +DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` +rm -f conftest.defs + + +# Without the "./", some shells look in PATH for config.status. +: ${CONFIG_STATUS=./config.status} + +echo creating $CONFIG_STATUS +rm -f $CONFIG_STATUS +cat > $CONFIG_STATUS <<EOF +#! /bin/sh +# Generated automatically by configure. +# Run this file to recreate the current configuration. +# This directory was configured as follows, +# on host `(hostname || uname -n) 2>/dev/null | sed 1q`: +# +# $0 $ac_configure_args +# +# Compiler output produced by configure, useful for debugging +# configure, is in ./config.log if it exists. + +ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" +for ac_option +do + case "\$ac_option" in + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" + exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; + -version | --version | --versio | --versi | --vers | --ver | --ve | --v) + echo "$CONFIG_STATUS generated by autoconf version 2.13" + exit 0 ;; + -help | --help | --hel | --he | --h) + echo "\$ac_cs_usage"; exit 0 ;; + *) echo "\$ac_cs_usage"; exit 1 ;; + esac +done + +ac_given_srcdir=$srcdir + +trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 +EOF +cat >> $CONFIG_STATUS <<EOF + +# Protect against being on the right side of a sed subst in config.status. +sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; + s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF +$ac_vpsub +$extrasub +s%@SHELL@%$SHELL%g +s%@CFLAGS@%$CFLAGS%g +s%@CPPFLAGS@%$CPPFLAGS%g +s%@CXXFLAGS@%$CXXFLAGS%g +s%@FFLAGS@%$FFLAGS%g +s%@DEFS@%$DEFS%g +s%@LDFLAGS@%$LDFLAGS%g +s%@LIBS@%$LIBS%g +s%@exec_prefix@%$exec_prefix%g +s%@prefix@%$prefix%g +s%@program_transform_name@%$program_transform_name%g +s%@bindir@%$bindir%g +s%@sbindir@%$sbindir%g +s%@libexecdir@%$libexecdir%g +s%@datadir@%$datadir%g +s%@sysconfdir@%$sysconfdir%g +s%@sharedstatedir@%$sharedstatedir%g +s%@localstatedir@%$localstatedir%g +s%@libdir@%$libdir%g +s%@includedir@%$includedir%g +s%@oldincludedir@%$oldincludedir%g +s%@infodir@%$infodir%g +s%@mandir@%$mandir%g +s%@host@%$host%g +s%@host_alias@%$host_alias%g +s%@host_cpu@%$host_cpu%g +s%@host_vendor@%$host_vendor%g +s%@host_os@%$host_os%g +s%@target@%$target%g +s%@target_alias@%$target_alias%g +s%@target_cpu@%$target_cpu%g +s%@target_vendor@%$target_vendor%g +s%@target_os@%$target_os%g +s%@build@%$build%g +s%@build_alias@%$build_alias%g +s%@build_cpu@%$build_cpu%g +s%@build_vendor@%$build_vendor%g +s%@build_os@%$build_os%g +s%@CC@%$CC%g +s%@build_exeext@%$build_exeext%g + +CEOF +EOF + +cat >> $CONFIG_STATUS <<\EOF + +# Split the substitutions into bite-sized pieces for seds with +# small command number limits, like on Digital OSF/1 and HP-UX. +ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. +ac_file=1 # Number of current file. +ac_beg=1 # First line for current file. +ac_end=$ac_max_sed_cmds # Line after last line for current file. +ac_more_lines=: +ac_sed_cmds="" +while $ac_more_lines; do + if test $ac_beg -gt 1; then + sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file + else + sed "${ac_end}q" conftest.subs > conftest.s$ac_file + fi + if test ! -s conftest.s$ac_file; then + ac_more_lines=false + rm -f conftest.s$ac_file + else + if test -z "$ac_sed_cmds"; then + ac_sed_cmds="sed -f conftest.s$ac_file" + else + ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" + fi + ac_file=`expr $ac_file + 1` + ac_beg=$ac_end + ac_end=`expr $ac_end + $ac_max_sed_cmds` + fi +done +if test -z "$ac_sed_cmds"; then + ac_sed_cmds=cat +fi +EOF + +cat >> $CONFIG_STATUS <<EOF + +CONFIG_FILES=\${CONFIG_FILES-"Makefile"} +EOF +cat >> $CONFIG_STATUS <<\EOF +for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then + # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". + case "$ac_file" in + *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` + ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; + *) ac_file_in="${ac_file}.in" ;; + esac + + # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. + + # Remove last slash and all that follows it. Not all systems have dirname. + ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` + if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then + # The file is in a subdirectory. + test ! -d "$ac_dir" && mkdir "$ac_dir" + ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" + # A "../" for each directory in $ac_dir_suffix. + ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` + else + ac_dir_suffix= ac_dots= + fi + + case "$ac_given_srcdir" in + .) srcdir=. + if test -z "$ac_dots"; then top_srcdir=. + else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; + /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; + *) # Relative path. + srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" + top_srcdir="$ac_dots$ac_given_srcdir" ;; + esac + + + echo creating "$ac_file" + rm -f "$ac_file" + configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." + case "$ac_file" in + *Makefile*) ac_comsub="1i\\ +# $configure_input" ;; + *) ac_comsub= ;; + esac + + ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` + sed -e "$ac_comsub +s%@configure_input@%$configure_input%g +s%@srcdir@%$srcdir%g +s%@top_srcdir@%$top_srcdir%g +" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file +fi; done +rm -f conftest.s* + +EOF +cat >> $CONFIG_STATUS <<EOF + +EOF +cat >> $CONFIG_STATUS <<\EOF + +exit 0 +EOF +chmod +x $CONFIG_STATUS +rm -fr confdefs* $ac_clean_files +test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 + diff --git a/winsup/doc/configure.in b/winsup/doc/configure.in new file mode 100644 index 000000000..a51a474a9 --- /dev/null +++ b/winsup/doc/configure.in @@ -0,0 +1,54 @@ +dnl Autoconf configure script for winsup/regexp +dnl Copyright 1997 Cygnus Solutions. +dnl +dnl This file is part of Cygwin. +dnl +dnl This software is a copyrighted work licensed under the terms of the +dnl Cygwin license. Please consult the file "CYGWIN_LICENSE" for +dnl details. + +dnl Process this file with autoconf to produce a configure script. + +AC_PREREQ(2.12) +AC_INIT(cygwin-api.in.sgml) + +AC_DEFUN(LIB_AC_PROG_CC, +[AC_BEFORE([$0], [AC_PROG_CPP])dnl +AC_CHECK_TOOL(CC, gcc, gcc) +if test -z "$CC"; then + AC_CHECK_PROG(CC, cc, cc, , , /usr/ucb/cc) + test -z "$CC" && AC_MSG_ERROR([no acceptable cc found in \$PATH]) +fi + +if test $ac_cv_prog_gcc = yes; then + GCC=yes +dnl Check whether -g works, even if CFLAGS is set, in case the package +dnl plays around with CFLAGS (such as to build both debugging and +dnl normal versions of a library), tasteless as that idea is. + ac_test_CFLAGS="${CFLAGS+set}" + ac_save_CFLAGS="$CFLAGS" + CFLAGS= + AC_PROG_CC_G + if test "$ac_test_CFLAGS" = set; then + CFLAGS="$ac_save_CFLAGS" + elif test $ac_cv_prog_cc_g = yes; then + CFLAGS="-g -O2" + else + CFLAGS="-O2" + fi + if test "$ac_test_CXXFLAGS" != set; then + CXXFLAGS='$(CFLAGS)' + fi +else + GCC= + test "${CFLAGS+set}" = set || CFLAGS="-g" +fi +]) + +AC_CANONICAL_SYSTEM + +LIB_AC_PROG_CC + +AC_SUBST(build_exeext) + +AC_OUTPUT(Makefile) diff --git a/winsup/doc/copy.texinfo b/winsup/doc/copy.texinfo new file mode 100644 index 000000000..90dc078d1 --- /dev/null +++ b/winsup/doc/copy.texinfo @@ -0,0 +1,382 @@ +@chapter What are the copyrights ? + +@section The general idea + +Most of the tools are covered by the GNU General Public License (GPL), +although some are public domain, and others have a X11-style +copyright. To cover the GNU GPL +requirements, the basic rule is if you give out any binaries, you must +also make the source available. For the full details, be sure to +read the text of the GNU GPL which follows. + +The Cygwin API library found in the winsup subdirectory of the +source code is also covered by the GNU GPL. By default, all +executables link against this library (and in the process include GPL'd +Cygwin glue code). This means that unless you modify the tools +so that compiled executables do not make use of the Cygwin library, +your compiled programs will also have to be free software distributed +under the GPL with source code available to all. + +Cygwin is currently available for proprietary use only through a +proprietary-use license. Please contact sales@@cygnus.com for +more information. + +In accordance with section 10 of the GPL, Cygnus permits programs whose +sources are distributed under a license that complies with the Open +Source definition to be linked with libcygwin.a without libcygwin.a +itself causing the resulting program to be covered by the GNU GPL. + +This means that you can port an Open Source(tm) application to cygwin, +and distribute that executable as if it didn't include a copy of +libcygwin.a linked into it. Note that this does not apply to the cygwin +DLL itself. If you distribute a (possibly modified) version of the DLL +you must adhere to the terms of the GPL, i.e., you must provide sources +for the cygwin DLL. + +See http://www.opensource.org/osd.html for the precise Open Source +Definition referenced above. + +@section GNU GENERAL PUBLIC LICENSE +@example + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 675 Mass Ave, Cambridge, MA 02139, USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) 19yy <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@end example + diff --git a/winsup/doc/cygwin-api.in.sgml b/winsup/doc/cygwin-api.in.sgml new file mode 100644 index 000000000..13d7f8c2f --- /dev/null +++ b/winsup/doc/cygwin-api.in.sgml @@ -0,0 +1,68 @@ +<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ + <!ENTITY cygnus-copyright "<YEAR>1998</YEAR><HOLDER>Cygnus + Solutions</HOLDER>"> + <!ENTITY cygnus-code-copyright " +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Copyright (C) 1998 Cygnus Solutions. + +This is copyrighted software that may only +be reproduced, modified, or distributed +under license from Cygnus Solutions. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +"> + ]> + +<book id="cygwin-api"> + + <bookinfo> + <date>1998-08-31</date> + <title>Cygwin API Reference</title> + <authorgroup> + <author> + <firstname>DJ</firstname> + <surname>Delorie</surname> + </author> + <author> + <firstname>Geoffrey</firstname> + <surname>Noer</surname> + </author> + </authorgroup> + + DOCTOOL-INSERT-legal + + <revhistory> + <revision> + <revnumber>0.0</revnumber> + <date>1998-08-31</date> + <authorinitials>dj@cygnus.com</authorinitials> + <revremark>Initial revision</revremark> + </revision> + <revision> + <revnumber>0.5.0</revnumber> + <date>1998-12-17</date> + <authorinitials>noer@cygnus.com</authorinitials> + <revremark>Add pthread, sem calls. Change revnumber to + three-part number: Cygwin API major, Cygwin API minor, Doc rev + number. Starts out at 0.5.0.</revremark> + </revision> + </revhistory> + </bookinfo> + + <toc></toc> + +<chapter id="compatibility"><title>Compatibility</title> +DOCTOOL-INSERT-std-ansi +DOCTOOL-INSERT-std-posix +DOCTOOL-INSERT-std-misc +</chapter> + +<chapter id="cygwin-functions"><title>Cygwin Functions</title> + +<para>These functions are specific to Cygwin itself, and probably +won't be found anywhere else. </para> + +DOCTOOL-INSERT-func- + +</chapter> + +</book> diff --git a/winsup/doc/cygwin-ug-net.in.sgml b/winsup/doc/cygwin-ug-net.in.sgml new file mode 100644 index 000000000..633689631 --- /dev/null +++ b/winsup/doc/cygwin-ug-net.in.sgml @@ -0,0 +1,64 @@ +<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ + <!ENTITY cygnus-copyright + "<YEAR>1999</YEAR> + <HOLDER>Cygnus Solutions</HOLDER>"> + <!ENTITY cygnus-code-copyright " +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Copyright (C) 1998, 1999 Cygnus Solutions. + +This is copyrighted software that may only +be reproduced, modified, or distributed +under license from Cygnus Solutions. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +"> + ]> + +<book id="cygwin-ug-net"> + + <bookinfo> + <date>1999-02-08</date> + <title>Cygwin User's Guide</title> + <authorgroup> + <author> + <firstname>DJ</firstname> + <surname>Delorie</surname> + </author> + <author> + <firstname>Pierre</firstname> + <surname>Humblet</surname> + </author> + <author> + <firstname>Geoffrey</firstname> + <surname>Noer</surname> + </author> + </authorgroup> + +DOCTOOL-INSERT-legal + + <revhistory> + <revision> + <revnumber>0.0</revnumber> + <date>1998-10-06</date> + <authorinitials>noer@cygnus.com</authorinitials> + <revremark>Initial revision</revremark> + </revision> + <revision> + <revnumber>20.1.0</revnumber> + <date>1999-02-08</date> + <authorinitials>Pierre.Humblet@eurecom.fr</authorinitials> + <revremark>Expand, describe Cygwin 20.1</revremark> + </revision> + </revhistory> + </bookinfo> + + <toc></toc> + +DOCTOOL-INSERT-overview + +DOCTOOL-INSERT-setup-net + +DOCTOOL-INSERT-using + +DOCTOOL-INSERT-programming + +</book> diff --git a/winsup/doc/cygwin-ug.in.sgml b/winsup/doc/cygwin-ug.in.sgml new file mode 100644 index 000000000..3a7371a88 --- /dev/null +++ b/winsup/doc/cygwin-ug.in.sgml @@ -0,0 +1,63 @@ +<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ + <!ENTITY cygnus-copyright "<YEAR>1999</YEAR> + <HOLDER>Cygnus Solutions</HOLDER>"> + <!ENTITY cygnus-code-copyright " +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Copyright (C) 1998, 1999 Cygnus Solutions. + +This is copyrighted software that may only +be reproduced, modified, or distributed +under license from Cygnus Solutions. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +"> + ]> + +<book id="cygwin-ug"> + + <bookinfo> + <date>1998-01-28</date> + <title>Cygwin User's Guide</title> + <authorgroup> + <author> + <firstname>DJ</firstname> + <surname>Delorie</surname> + </author> + <author> + <firstname>Pierre</firstname> + <surname>Humblet</surname> + </author> + <author> + <firstname>Geoffrey</firstname> + <surname>Noer</surname> + </author> + </authorgroup> + +DOCTOOL-INSERT-legal + + <revhistory> + <revision> + <revnumber>0.0</revnumber> + <date>1998-08-31</date> + <authorinitials>dj@cygnus.com</authorinitials> + <revremark>Initial revision</revremark> + </revision> + <revision> + <revnumber>20.1.0</revnumber> + <date>1999-02-08</date> + <authorinitials>Pierre.Humblet@eurecom.fr</authorinitials> + <revremark>Expand, describe Cygwin 20.1</revremark> + </revision> + </revhistory> + </bookinfo> + + <toc></toc> + +DOCTOOL-INSERT-overview + +DOCTOOL-INSERT-setup + +DOCTOOL-INSERT-using + +DOCTOOL-INSERT-programming + +</book> diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml new file mode 100644 index 000000000..8f5de3ec6 --- /dev/null +++ b/winsup/doc/cygwinenv.sgml @@ -0,0 +1,91 @@ +<sect1 id="using-cygwinenv"><title>The <EnVar>CYGWIN</EnVar> environment +variable</title> + +<para>The <EnVar>CYGWIN</EnVar> environment variable is used to configure +many global settings for the Cygwin runtime system. It contains the options +listed below, separated by blank characters. Many options can be turned off +by prefixing with <literal>no </literal>.</para> + +<itemizedlist Mark="bullet"> +<listitem> +<para><FirstTerm>(no)binmode</FirstTerm> - if set, non-disk +(e.g. pipe and COM ports) file opens default to binary mode +(no CR/LF/Ctrl-Z translations) instead of text mode. +Defaults to set (binary mode). This option must be set +before starting a Cygwin shell to have an effect on redirection. +</para> +<warning><title>Warning!</title><para>If set in 12/98 b20.1, all files +always open in binary mode.</para> </warning> +</listitem> +<listitem> +<para><FirstTerm>(no)envcache</FirstTerm> - If set, environment variable +conversions (between Win32 and POSIX) are cached. Note that this is may +cause problems if the mount table changes, as the cache is not invalidated +and may contain values that depend on the previous mount table +contents. Defaults to set.</para> +</listitem> +<listitem> +<para><FirstTerm>(no)export</FirstTerm> - if set, the final values of these +settings are re-exported to the environment as $CYGWIN again.</para> +</listitem> +<listitem> +<para><FirstTerm>(no)glob</FirstTerm> - if set, command line arguments +containing UNIX-style file wildcard characters (brackets, question mark, +asterisk, escaped with \) are expanded into lists of files that match +those wildcards. +This is applicable only to programs running from a DOS command line prompt. +Default is set.</para> +</listitem> +<listitem> +<para><FirstTerm>(no)ntea</FirstTerm> - if set, use the full NT Extended +Attributes to store UNIX-like inode information. +This option only operates under Windows NT. Defaults to not set. </para> +<Warning><Title>Warning!</Title> <para>This may create additional +<emphasis>large</emphasis> files on non-NTFS partitions.</para></Warning> +</listitem> +<listitem> +<para><FirstTerm>(no)ntsec</FirstTerm> - if set, use the NT security +model to set UNIX-like permissions on files and processes. The +file permissions can only be set on NTFS partitions. FAT and SAMBA doesn't +support the NT file security. For more information, read the documentation +in <citation>ntsec.sgml</citation>.</para> +</listitem> +<listitem> +<para><FirstTerm>(no)reset_com</FirstTerm> - if set, serial ports are reset +to 9600-8-N-1 with no flow control when used. This is done at open +time and when handles are inherited. Defaults to set.</para> +</listitem> +<listitem> +<para><FirstTerm>strace=n[:cache][,filename]</FirstTerm> - configures system +tracing. Off by default, setting various bits in <literal>n</literal> (a +bit flag) enables various types of system messages. Setting +<literal>n</literal> to 1 enables most messages. Other values can be found +in <filename>sys/strace.h</filename>. The <literal>:cache</literal> option +lets you specify how many lines to cache before flushing the output +(example: <literal>strace=1:20</literal>). The <literal>filename</literal> +option lets you send the messages to a file instead of the screen. </para> +</listitem> +<listitem> +<para><FirstTerm>(no)strip_title</FirstTerm> - if set, strips the directory +part off the window title, if any. Default is not set.</para> +</listitem> +<listitem> +<para><FirstTerm>(no)title</FirstTerm> - if set, the title bar +reflects the name of the program currently running. Default is not +set. Note that under Win9x the title bar is always enabled and it is +stripped by default, but this is because of the way Win9x works. In +order not to strip, specify <literal>title</literal> or <literal>title +nostrip_title</literal>.</para> +</listitem> +<listitem> +<para><FirstTerm>(no)tty</FirstTerm> - if set, Cygwin enables extra support +(i.e., termios) for UNIX-like ttys. +It is not compatible with some Windows programs. +Defaults to not set, in which case the tty is opened in text mode +with ^Z as EOF. Note that this has been changed such that ^D works as +expected instead of ^Z, and is settable via stty. +This option must be specified before starting a Cygwin shell +and it cannot be changed in the shell.</para> +</listitem> +</itemizedlist> +</sect1> diff --git a/winsup/doc/dll.sgml b/winsup/doc/dll.sgml new file mode 100644 index 000000000..274f12926 --- /dev/null +++ b/winsup/doc/dll.sgml @@ -0,0 +1,120 @@ +<sect1 id="dll"><title>Building and Using DLLs</title> + +<para>DLLs are Dynamic Link Libraries, which means that they're linked +into your program at run time instead of build time. There are three +parts to a DLL:</para> + +<itemizedlist spacing="compact"> +<listitem><para> the exports </para></listitem> +<listitem><para> the code and data </para></listitem> +<listitem><para> the import library </para></listitem> +</itemizedlist> + +<para>The code and data are the parts you write - functions, +variables, etc. All these are merged together, like if you were +building one big object files, and put into the dll. They are not +put into your .exe at all.</para> + +<para>The exports contains a list of functions and variables that the +dll makes available to other programs. Think of this as the list of +"global" symbols, the rest being hidden. Normally, you'd create this +list by hand with a text editor, but it's possible to do it +automatically from the list of functions in your code. The +<filename>dlltool</filename> program creates the exports section of +the dll from your text file of exported symbols.</para> + +<para>The import library is a regular UNIX-like +<filename>.a</filename> library, but it only contains the tiny bit of +information needed to tell the OS how your program interacts with +("imports") the dll. This information is linked into your +<filename>.exe</filename>. This is also generated by +<filename>dlltool</filename>.</para> + +<sect2 id="dll-build"><title>Building DLLs</title> + +<para>OK, let's go through a simple example of how to build a dll. +For this example, we'll use a single file +<filename>myprog.c</filename> for the program +(<filename>myprog.exe</filename>) and a single file +<filename>mydll.c</filename> for the contents of the dll +(<filename>mydll.dll</filename>).</para> + +<para>Now compile everything to objects:</para> + +<screen> +gcc -c myprog.c +gcc -c mydll.c +</screen> + +<para>Unfortunately, the process for building a dll is, well, convoluted. +You have to run five commands, like this:</para> + +<screen> +gcc -s -Wl,--base-file,mydll.base -o mydll.dll mydll.o -Wl,-e,_mydll_init@12 +dlltool --base-file mydll.base --def mydll.def --output-exp mydll.exp --dllname mydll.dll +gcc -s -Wl,--base-file,mydll.base,mydll.exp -o mydll.dll mydll.o -Wl,-e,_mydll_init@12 +dlltool --base-file mydll.base --def mydll.def --output-exp mydll.exp --dllname mydll.dll +gcc -Wl,mydll.exp -o mydll.dll mydll.o -Wl,-e,_mydll_init@12 +</screen> + +<para>The extra steps give <filename>dlltool</filename> the +opportunity to generate the extra sections (exports and relocation) +that a dll needs. After this, you build the import library:</para> + +<screen> +dlltool --def mydll.def --dllname mydll.dll --output-lib mydll.a +</screen> + +<para>Now, when you build your program, you link against the import +library:</para> + +<screen> +gcc -o myprog myprog.o mydll.a +</screen> + +<para>Note that we linked with <command>-e _mydll_init@12</command>. +This tells the OS what the DLL's "entry point" is, and this is a +special function that coordinates bringing the dll to life withing the +OS. The minimum function looks like this:</para> + +<screen> +#include <windows.h> + +int WINAPI +mydll_init(HANDLE h, DWORD reason, void *foo) +{ + return 1; +} +</screen> + +</sect2> + +<sect2 id="dll-link"><title>Linking Against DLLs</title> + +<para>If you have an existing DLL already, you need to build a +Cygwin-compatible import library (The supplied ones should work, but +you might not have them) to link against. Unfortunately, there is not +yet any tool to do this automatically. However, you can get most of +the way by creating a .def file with these commands (you might need to +do this in <filename>bash</filename> for the quoting to work +correctly):</para> + +<screen> +echo EXPORTS > foo.def +nm foo.dll | grep ' T _' | sed 's/.* T _//' >> foo.def +</screen> + +<para>Note that this will only work if the DLL is not stripped. +Otherwise you will get an error message: "No symbols in +foo.dll".</para> + +<para>Once you have the <filename>.def</filename> file, you can create +an import library from it like this:</para> + +<screen> +dlltool --def foo.def --dllname foo.dll --output-lib foo.a +</screen> + +</sect2> + +</sect1> diff --git a/winsup/doc/doctool.c b/winsup/doc/doctool.c new file mode 100644 index 000000000..26e76669d --- /dev/null +++ b/winsup/doc/doctool.c @@ -0,0 +1,622 @@ +/* doctool.c + + Copyright 1998 Cygnus Solutions. + +This file is part of Cygwin. + +This software is a copyrighted work licensed under the terms of the +Cygwin license. Please consult the file "CYGWIN_LICENSE" for +details. */ + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <dirent.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <utime.h> + +/* Building native in a cross-built directory is tricky. Be careful, +and beware that you don't have the full portability stuff available to +you (like libiberty) */ + +/*****************************************************************************/ + +/* The list of extensions that may contain SGML snippets. We check + both cases in case the file system isn't case sensitive enough. */ + +struct { + char *upper; + char *lower; + int is_sgml; +} extensions[] = { + { ".C", ".c", 0 }, + { ".CC", ".cc", 0 }, + { ".H", ".h", 0 }, + { ".SGML", ".sgml", 1 }, + { 0, 0, 0 } +}; + +/*****************************************************************************/ + +void +show_help() +{ + printf("Usage: doctool [-m] [-i] [-d dir] [-o outfile] [-s prefix] \\\n"); + printf(" [-b book_id] infile\n"); + printf(" -m means to adjust Makefile to include new dependencies\n"); + printf(" -i means to include internal snippets\n"); + printf(" -d means to recursively scan directory for snippets\n"); + printf(" -o means to output to file (else stdout)\n"); + printf(" -s means to suppress source dir prefix\n"); + printf(" -b means to change the <book id=\"book_id\">\n"); + printf("\n"); + printf("doctool looks for DOCTOOL-START and DOCTOOL-END lines in source,\n"); + printf("saves <foo id=\"bar\"> blocks, and looks for DOCTOOL-INSERT-bar\n"); + printf("commands to insert selected sections. IDs starting with int-\n"); + printf("are internal only, add- are added at the end of relevant sections\n"); + printf("or add-int- for both. Inserted sections are chosen by prefix,\n"); + printf("and sorted when inserted.\n"); + exit(1); +} + +/*****************************************************************************/ + +typedef struct Section { + struct Section *next; + struct OneFile *file; + char *name; + char internal; + char addend; + char used; + char **lines; + int num_lines; + int max_lines; +} Section; + +typedef struct OneFile { + struct OneFile *next; + char *filename; + int enable_scan; + int used; + Section *sections; +} OneFile; + +OneFile *file_list = 0; + +char *output_name = 0; +FILE *output_file = 0; + +char *source_dir_prefix = ""; +char *book_id = 0; + +int internal_flag = 0; + +/*****************************************************************************/ + +char * +has_string(char *line, char *string) +{ + int i; + while (*line) + { + for (i=0; line[i]; i++) + { + if (!string[i]) + return line; + if (line[i] != string[i]) + break; + } + line++; + } + return 0; +} + +int +starts_with(char *line, char *string) +{ + int i=0; + while (1) + { + if (!string[i]) + return 1; + if (!line[i] || line[i] != string[i]) + return 0; + i++; + } +} + +/*****************************************************************************/ + +#ifdef S_ISLNK +#define STAT lstat +#else +#define STAT stat +#endif + +void +scan_directory(dirname) + char *dirname; +{ + struct stat st; + char *name; + struct dirent *de; + DIR *dir = opendir(dirname); + if (!dir) + return; + while (de = readdir(dir)) + { + if (strcmp(de->d_name, ".") == 0 + || strcmp(de->d_name, "..") == 0) + continue; + + name = (char *)malloc(strlen(dirname)+strlen(de->d_name)+3); + strcpy(name, dirname); + strcat(name, "/"); + strcat(name, de->d_name); + + STAT(name, &st); + + if (S_ISDIR(st.st_mode)) + { + scan_directory(name); + } + + else if (S_ISREG(st.st_mode)) + { + char *dot = strrchr(de->d_name, '.'); + int i; + + if (dot) + { + for (i=0; extensions[i].upper; i++) + if (strcmp(dot, extensions[i].upper) == 0 + || strcmp(dot, extensions[i].lower) == 0) + { + OneFile *one = (OneFile *)malloc(sizeof(OneFile)); + one->next = file_list; + file_list = one; + one->filename = name; + one->enable_scan = ! extensions[i].is_sgml; + one->used = 0; + one->sections = 0; + } + } + } + } + closedir (dir); +} + +/*****************************************************************************/ + +void +scan_file(OneFile *one) +{ + FILE *f = fopen(one->filename, "r"); + int enabled = ! one->enable_scan; + char line[1000], *tag=0, *id=0, *tmp; + int taglen = 0; + Section *section = 0; + Section **prev_section_ptr = &(one->sections); + + if (!f) + { + perror(one->filename); + return; + } + + while (fgets(line, 1000, f)) + { + if (one->enable_scan) + { + /* source files have comment-embedded docs, check for them */ + if (has_string(line, "DOCTOOL-START")) + enabled = 1; + if (has_string(line, "DOCTOOL-END")) + enabled = 0; + } + if (!enabled) + continue; + + /* DOCTOOL-START + +<sect1 id="dt-tags"> +this is the doctool tags section. +</sect1> + + DOCTOOL-END */ + + if (!tag && line[0] == '<') + { + tag = (char *)malloc(strlen(line)+1); + id = (char *)malloc(strlen(line)+1); + if (sscanf(line, "<%s id=\"%[^\"]\">", tag, id) == 2) + { + if (strcmp(tag, "book") == 0 || strcmp(tag, "BOOK") == 0) + { + /* Don't want to "scan" these */ + return; + } + taglen = strlen(tag); + section = (Section *)malloc(sizeof(Section)); + /* We want chunks within single files to appear in that order */ + section->next = 0; + section->file = one; + *prev_section_ptr = section; + prev_section_ptr = &(section->next); + section->internal = 0; + section->addend = 0; + section->used = 0; + section->name = id; + if (starts_with(section->name, "add-")) + { + section->addend = 1; + section->name += 4; + } + if (starts_with(section->name, "int-")) + { + section->internal = 1; + section->name += 4; + } + section->lines = (char **)malloc(10*sizeof(char *)); + section->num_lines = 0; + section->max_lines = 10; + } + else + { + free(tag); + free(id); + tag = id = 0; + } + } + + if (tag && section) + { + if (section->num_lines >= section->max_lines) + { + section->max_lines += 10; + section->lines = (char **)realloc(section->lines, + section->max_lines * sizeof (char *)); + } + section->lines[section->num_lines] = (char *)malloc(strlen(line)+1); + strcpy(section->lines[section->num_lines], line); + section->num_lines++; + + if (line[0] == '<' && line[1] == '/' + && memcmp(line+2, tag, taglen) == 0 + && (isspace(line[2+taglen]) || line[2+taglen] == '>')) + { + /* last line! */ + tag = 0; + } + } + } + fclose(f); +} + +/*****************************************************************************/ + +Section ** +enumerate_matching_sections(char *name_prefix, int internal, int addend, int *count_ret) +{ + Section **rv = (Section **)malloc(12*sizeof(Section *)); + int count = 0, max=10, prefix_len = strlen(name_prefix); + OneFile *one; + int wildcard = 0; + + if (name_prefix[strlen(name_prefix)-1] == '-') + wildcard = 1; + + for (one=file_list; one; one=one->next) + { + Section *s; + for (s=one->sections; s; s=s->next) + { + int matches = 0; + if (wildcard) + { + if (starts_with(s->name, name_prefix)) + matches = 1; + } + else + { + if (strcmp(s->name, name_prefix) == 0) + matches = 1; + } + if (s->internal <= internal + && s->addend == addend + && matches + && ! s->used) + { + s->used = 1; + if (count >= max) + { + max += 10; + rv = (Section **)realloc(rv, max*sizeof(Section *)); + } + rv[count++] = s; + rv[count] = 0; + } + } + } + if (count_ret) + *count_ret = count; + return rv; +} + +/*****************************************************************************/ + +#define ID_CHARS "~@$%&()_-+[]{}:." + +void include_section(char *name, int addend); + +char * +unprefix(char *fn) +{ + int l = strlen(source_dir_prefix); + if (memcmp(fn, source_dir_prefix, l) == 0) + { + fn += l; + while (*fn == '/' || *fn == '\\') + fn++; + return fn; + } + return fn; +} + +void +parse_line(char *line, char *filename) +{ + char *cmd = has_string(line, "DOCTOOL-INSERT-"); + char *sname, *send, *id, *save; + if (!cmd) + { + if (book_id + && (starts_with(line, "<book") || starts_with(line, "<BOOK"))) + { + cmd = strchr(line, '>'); + if (cmd) + { + cmd++; + fprintf(output_file, "<book id=\"%s\">", book_id); + fputs(cmd, output_file); + return; + } + } + fputs(line, output_file); + return; + } + if (cmd != line) + fwrite(line, cmd-line, 1, output_file); + save = (char *)malloc(strlen(line)+1); + strcpy(save, line); + line = save; + + sname = cmd + 15; /* strlen("DOCTOOL-INSERT-") */ + for (send = sname; + *send && isalnum(*send) || strchr(ID_CHARS, *send); + send++); + id = (char *)malloc(send-sname+2); + memcpy(id, sname, send-sname); + id[send-sname] = 0; + include_section(id, 0); + + fprintf(output_file, "<!-- %s -->\n", unprefix(filename)); + + fputs(send, output_file); + free(save); +} + +int +section_sort(const void *va, const void *vb) +{ + Section *a = *(Section **)va; + Section *b = *(Section **)vb; + int rv = strcmp(a->name, b->name); + if (rv) + return rv; + return a->internal - b->internal; +} + +void +include_section(char *name, int addend) +{ + Section **sections, *s; + int count, i, l; + + sections = enumerate_matching_sections(name, internal_flag, addend, &count); + + qsort(sections, count, sizeof(sections[0]), section_sort); + for (i=0; i<count; i++) + { + s = sections[i]; + s->file->used = 1; + fprintf(output_file, "<!-- %s -->\n", unprefix(s->file->filename)); + for (l=addend; l<s->num_lines-1; l++) + parse_line(s->lines[l], s->file->filename); + if (!addend) + { + include_section(s->name, 1); + parse_line(s->lines[l], s->file->filename); + } + } + + free(sections); +} + +void +parse_sgml(FILE *in, char *input_name) +{ + static char line[1000]; + while (fgets(line, 1000, in)) + { + parse_line(line, input_name); + } +} + +/*****************************************************************************/ + +void +fix_makefile(char *output_name) +{ + FILE *in, *out; + char line[1000]; + int oname_len = strlen(output_name); + OneFile *one; + int used_something = 0; + struct stat st; + struct utimbuf times; + + stat("Makefile", &st); + + in = fopen("Makefile", "r"); + if (!in) + { + perror("Makefile"); + return; + } + + out = fopen("Makefile.new", "w"); + if (!out) + { + perror("Makefile.new"); + return; + } + + while (fgets(line, 1000, in)) + { + if (starts_with(line, output_name) + && strcmp(line+oname_len, ": \\\n") == 0) + { + /* this is the old dependency */ + while (fgets(line, 1000, in)) + { + if (strcmp(line+strlen(line)-2, "\\\n")) + break; + } + } + else + fputs(line, out); + } + fclose(in); + + for (one=file_list; one; one=one->next) + if (one->used) + { + used_something = 1; + break; + } + + if (used_something) + { + fprintf(out, "%s:", output_name); + for (one=file_list; one; one=one->next) + if (one->used) + fprintf(out, " \\\n\t%s", one->filename); + fprintf(out, "\n"); + } + + fclose(out); + + times.actime = st.st_atime; + times.modtime = st.st_mtime; + utime("Makefile.new", ×); + + if (rename("Makefile", "Makefile.old")) + return; + if (rename("Makefile.new", "Makefile")) + rename("Makefile.old", "Makefile"); +} + +/*****************************************************************************/ + +int +main(argc, argv) + int argc; + char **argv; +{ + int i; + OneFile *one; + FILE *input_file; + int fix_makefile_flag = 0; + + while (argc > 1 && argv[1][0] == '-') + { + if (strcmp(argv[1], "-h") == 0 || strcmp(argv[1], "--help") == 0) + { + show_help(); + } + else if (strcmp(argv[1], "-i") == 0) + { + internal_flag = 1; + } + else if (strcmp(argv[1], "-m") == 0) + { + fix_makefile_flag = 1; + } + else if (strcmp(argv[1], "-d") == 0 && argc > 2) + { + scan_directory(argv[2]); + argc--; + argv++; + } + else if (strcmp(argv[1], "-o") == 0 && argc > 2) + { + output_name = argv[2]; + argc--; + argv++; + } + else if (strcmp(argv[1], "-s") == 0 && argc > 2) + { + source_dir_prefix = argv[2]; + argc--; + argv++; + } + else if (strcmp(argv[1], "-b") == 0 && argc > 2) + { + book_id = argv[2]; + argc--; + argv++; + } + + argc--; + argv++; + } + + for (one=file_list; one; one=one->next) + { + scan_file(one); + } + + input_file = fopen(argv[1], "r"); + if (!input_file) + { + perror(argv[1]); + return 1; + } + + if (output_name) + { + output_file = fopen(output_name, "w"); + if (!output_file) + { + perror(output_name); + return 1; + } + } + else + { + output_file = stdout; + output_name = "<stdout>"; + } + + parse_sgml(input_file, argv[1]); + + if (output_file != stdout) + fclose(output_file); + + if (fix_makefile_flag) + fix_makefile(output_name); + + return 0; +} diff --git a/winsup/doc/doctool.txt b/winsup/doc/doctool.txt new file mode 100644 index 000000000..c89e39243 --- /dev/null +++ b/winsup/doc/doctool.txt @@ -0,0 +1,146 @@ +Doctool + +DJ Delorie <dj@cygnus.com> + +These are the instructions for using doctool. Yes, I should have +written them *in* DocBook, but hey, I was in a hurry. + +OK, doctool is a program that gathers snippets of a docbook document and +puts them all together in the right order. There are three +places that it gets snippets from: + +1. The document that you tell it you want "finished" + +2. blocks of SGML in *.sgml files + +3. comments in source code + +The first of these is the template file, which is to say, it's a +normal SGML file (sort of). This file is the first one read, and +includes such things as your <book> tags etc. It contains commands to +doctool to tell it where to put the other parts. + +The second, the *.sgml files, contain one or more blocks of SGML. +To work with doctool, each of these snippets must begin and end +with matching tags, must have an id="" attribute, and the start/end +tags must begin at the beginning of the line. For example: + +<foo id="frob-45"> + stuff goes here +</foo> +<bar id="frob-48"> + stuff goes here +</bar> + +In this example, the file contains two snippets, one marked by "foo" +and one barked by "bar", with id's "from-45" and "from-48". Note that +I made up the foo and bar tags. You'd usually use a <sect1> tag or +something useful like that. Stuff outside the blocks is ignored. + +The third is simply an encapsulation of the second in comments, like this: + +/* DOCTOOL-START +<foo id="frob-45"> + stuff goes here +</foo> +DOCTOOL-END */ + +The DOCTOOL-START and DOCTOOL-END things are special. Doctool uses +those to know which parts of which comments are useful, and which +parts are the useless source code stuff ;-) + + +OK, so now we've got all these snippets of SGML floating around. What +do we do with them? Well, inside the template document (#1 in our +list up there) you'd put text snippets that said "ok, put them +here". Each text snippet looks like this: + +DOCTOOL-INSERT-frob- + +Note that the "frob-" part tells doctool to pull in all the snippets +with IDs that start with "frob-", in alphabetical (well, asciibetical +at the moment) order. So, by saying "DOCTOOL-INSERT-frob-" you'd get +all the "frob-*" snippets, like "frob-45" and "frob-48". + +If you just said DOCTOOL-INSERT-frob, it inserts the snippet named +"frob" and no others. + +Note that no snippet will ever be inserted more than once, no matter +how many DOCTOOL-INSERTs you have. + +There's two other tricks doctool has. If it finds a snippet with an ID +like "int-*" (i.e. int-frob-45) that means that snippet of documentation +is for the "internal" version only. The "int-" is discarded, and if +the -i option is given to doctool, this snippet is treated as if the +int- wasn't there. Without the -i, the int-* snippets are ignored +completely. + +If a snippet has "add-" on it, like "add-frob-45", that's an addendum. +Each time a snippet named without the add- is found, doctool looks for +an addendum with exactly that same name (i.e. frob-45 looks for +add-frob-45). If it finds any, it puts them just before the last line +of the non-add snippet (so that it's *inside* the main snippet's +block, not after it). Example: + +<sect1 id="frob-45"> + some text +</sect1> +<sect1 id="add-frob-45"> + more text +</sect1> + +This would yield: + +<sect1 id="frob-45"> + some text + more text +</sect1> + +You should use the same outermost tags as the main snippet, but only +because it sets the proper nesting rules for what's enclosed. + +You can use add- and int- at the same time, but always do add-int- and +not int-add- (i.e. "add-int-frob-45"). + + +OK, now for doctool command line options. + +-m tells doctool to "fix" the Makefile (not makefile) to include the +extra dependencies needed by the file you're generating. You need to +manually include dependencies on the Makefile itself and the template +file; doctool only includes the snippet files (sources etc) that it +actually pulled content from. Note: this isn't perfect! Someone can +come along and add a new snippet to a source file, and doctool would +never know. Sometimes, it's best to just rebuild the docs all the +time. + +-i means to include snippets with the "int-" prefix on their IDs. Use +with -b to make internal and public versions from the same sources. + +"-d dir" tells doctool to scan all the files in that directory (and +subdirectories, recursively) for files that might contain snippets of +SGML. These include *.c, *.cc, *.h, and *.sgml. The idea is that +most of the documentation would be in a *.sgml file named after the +source (i.e. foo.c -> foo.sgml) but some commentary within the source +might be useful in the docs as well. SGML files (*.sgml) do not need +the DOCTOOL-START/END tags but the others do. + +-o sets the output file. Without -o, the file goes to stdout (ick). + +-s tells doctool to supress a "source directory prefix". What this +means is that, in the generated output doctool puts comments that say +where each snippet comes from (for debugging), which includes the full +path sometimes, but if you use -s, you can tell doctool to cut off +that prefix. For example, +/usr/people/dj/src/cygnus/latest/devo/winsup/foo.c might get shortened +to winsup/foo.c if you gave "-s +/usr/people/dj/src/cygnus/latest/devo/". Cygnus makefiles could +just use -s $(srcdir) most of the time. + +-b changes the ID for the <book> tag. db2html uses the <book> tag's +ID as the default subdirectory name and/or html file name to create +the book with. You'd need this to generate two books (internal vs +public) from the same source. + +The only other thing you'd add to the command line is the ONE template +file you want to pull in. diff --git a/winsup/doc/faq.texinfo b/winsup/doc/faq.texinfo new file mode 100644 index 000000000..7690088e4 --- /dev/null +++ b/winsup/doc/faq.texinfo @@ -0,0 +1,13 @@ +\input texinfo +@title The Cygwin Project FAQ 20.2 for Release B20.1. +@setfilename faq.txt + +@include what.texinfo +@include sites.texinfo +@include install.texinfo +@include calls.texinfo +@include how.texinfo +@include relnotes.texinfo +@include history.texinfo +@include who.texinfo +@include copy.texinfo diff --git a/winsup/doc/fhandler-tut.txt b/winsup/doc/fhandler-tut.txt new file mode 100644 index 000000000..52e08c768 --- /dev/null +++ b/winsup/doc/fhandler-tut.txt @@ -0,0 +1,83 @@ +fhandler tutorial + +This document will show how to add a new "fhandler" to cygwin, by +showing an example of /dev/zero. + +Files to note: + +fhandler.h - must define a new derived class here and FH_* +path.cc - to notice "/dev/zero" and mark it +fhandler_zero.cc - new +hinfo.cc - to create the fhandler instance + +OK, first we have to define what this new fhandler will do. In our +example case, we're going to implement the unix "/dev/zero" device, +which has the following characteristics: + +* writes to /dev/zero are silently discarded +* reads from /dev/zero return all zero bytes +* mmap()ing /dev/zero maps a chunk of zero'd out memory. + +Since windows doesn't have a device that acts like this, we'll be +simulating everything. Thus: + +* writes simply return a success status +* reads memset() the buffer and return success +* we take advantage of the fact that CreateFileMapping can take a + handle of -1, which (1) maps swap memory, and (2) zeros it out for + us (at least, on NT). + +OK, let's start with fhandler.h. + +First, update the comment about which files are where. We're adding +fhandler_dev_zero as FH_DEV_ZERO. We're adding this as a "fast" +device (it will never block) so we have to adjust FH_NDEV also. + +Later in that file, we'll copy fhandler_dev_null and edit it to be +fhandler_dev_zero. I chose that one because it's small, but we'll add +more members as we go (since we're simulating the whole thing). In +fact, let's copy the I/O methods from fhandler_windows since we'll +need all those anyway, even though we'll go through the full list +later. + +OK, next we need to edit path.cc to recognize when the user is trying +to open "/dev/zero". Look in get_device_number; there's a long list +of cases, just add one (I added one after "null"). Also remember to +add an entry to the windows_device_names list in the right spot. + +To go along with that change, we'll need to change hinfo.cc. Look for +FH_NULL and add a case for FH_ZERO as well. + +Now we get to fhandler_zero.cc itself. Create the empty file and copy +the "usual" header/copyright/includes from some other fhandler_*.cc +source file. Also, edit Makefile.in to build this new file. Add one +new entry to DLL_OFILES, and a new line for the winsup.h dependencies. + +Since we changed fhandler.h, when you type "make" it will rebuild +everything. Go ahead and do that when you get a chance to let it run, +since we're not changing the headers any more. Note that you won't be +able to link the new dll, as we haven't added all the methods for the +new fhandler class yet, but at least you'll get a lot of compilation +out of the way. + +Next we start adding in the fhandler methods themselves. + +Constructor: This takes a name, and all we do is pass that name back +to the base class, along with the FH_ZERO value. We call set_cb +because all fhandlers call this (it's for exec to copy the fd). + +open: we override the one that takes a name because there are no real +windows devices like /dev/zero, but we ignore the name. We call +set_flags to save the flags. + +write: writes are discarded; we return success. + +read: reads read NUL bytes, so fill the buffer with NULs and return +success. + +lseek/close: just return success. + +dump: this is just for debugging, so we just print something. + +select_*: we don't support this yet, see the myriad examples in +select.cc for examples. The base fhandler's methods will do for now. diff --git a/winsup/doc/filemodes.sgml b/winsup/doc/filemodes.sgml new file mode 100644 index 000000000..b0bac2eef --- /dev/null +++ b/winsup/doc/filemodes.sgml @@ -0,0 +1,34 @@ +<sect1 id="using-filemodes"><title>File permissions</title> + +<para>On Windows 9x systems, files are always readable, and Cygwin uses the +native read-only mode to determine if they are writable. Files are +considered to be executable if the filename ends with .bat, .com or .exe, or +if its content starts with #!. Consequently <command>chmod</command> can +only affect the "w" mode, it silently ignores actions involving the other +modes. This means that <command>ls -l</command> +needs to open and read files. It can thus be relatively slow.</para> + +<para>Under NT, file permissions default to the same behavior as Windows +9x but there is optional functionality in Cygwin that can make file +systems behave more like on UNIX systems. This is turned on by adding +the "ntea" option to the <EnVar>CYGWIN</EnVar> environment variable.</para> + +<para>When the "ntea" feature is activated, Cygwin will start with basic +permissions as determined above, but can store POSIX file permissions in NT +Extended Attributes. This feature works quite well on NTFS partitions +because the attributes can be stored sensibly inside the normal NTFS +filesystem structure. However, on a FAT partition, NT stores extended +attributes in a flat file at the root of the partition called <filename>EA +DATA. SF</filename>. This file can grow to extremely large sizes if you +have a large number of files on the partition in question, slowing the +system to a crawl. In addition, the <filename>EA DATA. SF</filename> file +can only be deleted outside of Windows because of its "in use" status. For +these reasons, the use of NT Extended Attributes is off by default in +Cygwin. Finally, note that specifying "ntea" in <EnVar>CYGWIN</EnVar> has no +effect under Windows 9x. </para> + +<para>Under NT, the test "[ -w filename]" is only true if filename is +writable across the board, e.g. <command>chmod +w filename</command>. </para> + +</sect1> + diff --git a/winsup/doc/gcc.sgml b/winsup/doc/gcc.sgml new file mode 100644 index 000000000..d13bba116 --- /dev/null +++ b/winsup/doc/gcc.sgml @@ -0,0 +1,78 @@ +<sect1 id="gcc"><title>Using GCC with Cygwin</title> + +<sect2 id="gcc-cons"><title>Console Mode Applications</title> + +<para>Use gcc to compile, just like under UNIX. +Refer to the GCC User's Guide for information on standard usage and +options. Here's a simple example:</para> + +<example> +<title>Building Hello World with GCC</title> +<screen> +<prompt>C:\cygnus\></prompt> <userinput>gcc hello.c -o hello.exe</userinput> +<prompt>C:\cygnus\></prompt> <userinput>hello.exe</userinput> +Hello, World + +<prompt>C:\cygnus\></prompt> +</screen> +</example> + +</sect2> + +<sect2 id="gcc-gui"><title>GUI Mode Applications</title> + +<para>Cygwin allows you to build programs with full access to the +standard Windows 32-bit API, including the GUI functions as defined in +any Microsoft or off-the-shelf publication. However, the process of +building those applications is slightly different, as you'll be using +the GNU tools instead of the Microsoft tools.</para> + +<para>For the most part, your sources won't need to change at all. +However, you should remove all __export attributes from functions +and replace them like this:</para> + +<screen> +int foo (int) __attribute__ ((__dllexport__)); + +int +foo (int i) +</screen> + +<para>For most cases, you can just remove the __export and leave it at +that. For convenience sake, you might want to include the following +code snippet when compiling GUI programs. If you don't, you will want +to add "-e _mainCRTStartup" to your link line in your Makefile.</para> + +<screen> +#ifdef __CYGWIN__ +WinMainCRTStartup() { mainCRTStartup(); } +#endif +</screen> + +<para>The Makefile is similar to any other UNIX-like Makefile, +and like any other Cygwin makefile. The only difference is that you use +<command>gcc -mwindows</command> to link your program into a GUI +application instead of a command-line application. Here's an example:</para> + +<screen> +myapp.exe : myapp.o myapp.res + gcc -mwindows myapp.o myapp.res -o $@ + +myapp.res : myapp.rc resource.h + windres $< -O coff -o $@ +</screen> + +<para>Note the use of <filename>windres</filename> to compile the +Windows resources into a COFF-format <filename>.res</filename> file. +That will include all the bitmaps, icons, and other resources you +need, into one handy object file. Normally, if you omitted the "-O +coff" it would create a Windows <filename>.res</filename> format file, +but we can only link COFF objects. So, we tell +<filename>windres</filename> to produce a COFF object, but for +compatibility with the many examples that assume your linker can +handle Windows resource files directly, we maintain the +<filename>.res</filename> naming convention. For more information on +<filename>windres</filename>, consult the Binutils manual. </para> + +</sect2> +</sect1> diff --git a/winsup/doc/gdb.sgml b/winsup/doc/gdb.sgml new file mode 100644 index 000000000..732004f49 --- /dev/null +++ b/winsup/doc/gdb.sgml @@ -0,0 +1,88 @@ + +<sect1 id="gdb"><title>Debugging Cygwin Programs</title> + +<para>When your program doesn't work right, it usually has a "bug" in +it, meaning there's something wrong with the program itself that is +causing unexpected results or crashes. Diagnosing these bugs and +fixing them is made easy by special tools called +<emphasis>debuggers</emphasis>. In the case of Cygwin, the debugger +is GDB, which stands for "GNU DeBugger". This tool lets you run your +program in a controlled environment where you can investigate the +state of your program while it is running or after it crashes. +Crashing programs sometimes create "core" files. In Cygwin these are +regular text files that cannot be used directly by GDB. +</para> + +<para>Before you can debug your program, you need to prepare your +program for debugging. What you need to do is add +<literal>-g</literal> to all the other flags you use when compiling +your sources to objects.</para> + +<example><title>Compiling with -g</title> +<screen> +<prompt>$</prompt> gcc -g -O2 -c myapp.c +<prompt>$</prompt> gcc -g myapp.c -o myapp +</screen> +</example> + +<para>What this does is add extra information to the objects (they get +much bigger too) that tell the debugger about line numbers, variable +names, and other useful things. These extra symbols and debugging +information give your program enough information about the original +sources so that the debugger can make debugging much easier for +you.</para> + +<para>In Windows versions of GNUPro, GDB comes with a full-featured +graphical interface. In Cygwin Net distributions, GDB is only +available as a command-line tool. To invoke GDB, simply type +<command>gdb myapp.exe</command> at the command prompt. It will +display some text telling you about itself, then +<literal>(gdb)</literal> will appear to prompt you to enter commands. +Whenever you see this prompt, it means that gdb is waiting for you to +type in a command, like <command>run</command> or +<command>help</command>. Oh <literal>:-)</literal> type +<command>help</command> to get help on the commands you can type in, +or read the <citation>GDB User's Manual</citation> for a complete +description of GDB and how to use it.</para> + +<para>If your program crashes and you're trying to figure out why it +crashed, the best thing to do is type <command>run</command> and let +your program run. After it crashes, you can type +<command>where</command> to find out where it crashed, or +<command>info locals</command> to see the values of all the local +variables. There's also a <command>print</command> that lets you look +at individual variables or what pointers point to.</para> + +<para>If your program is doing something unexpected, you can use the +<command>break</command> command to tell gdb to stop your program when it +gets to a specific function or line number:</para> + +<example><title>"break" in gdb</title> +<screen> +<prompt>(gdb)</prompt> break my_function +<prompt>(gdb)</prompt> break 47 +</screen> +</example> + +<para>Now, when you type <command>run</command> your program will stop +at that "breakpoint" and you can use the other gdb commands to look at +the state of your program at that point, modify variables, and +<command>step</command> through your program's statements one at a +time.</para> + +<para>Note that you may specify additional arguments to the +<command>run</command> command to provide command-line arguments to +your program. These two cases are the same as far as your program is +concerned:</para> + +<example><title>Debugging with command line arguments</title> +<screen> +<prompt>$</prompt> myprog -t foo --queue 47 + +<prompt>$</prompt> gdb myprog +<prompt>(gdb)</prompt> run -t foo --queue 47 +</screen> +</example> + + +</sect1> diff --git a/winsup/doc/history.texinfo b/winsup/doc/history.texinfo new file mode 100644 index 000000000..2d5c4c0e8 --- /dev/null +++ b/winsup/doc/history.texinfo @@ -0,0 +1,667 @@ +@chapter History + +@include changes.texinfo + +@section Release Beta 19 (Feb 26 1998) + +This is a major release. It includes a much-updated version of the +Cygwin32 library. Because the Cygwin API has changed in incompatible +ways, the dll has been renamed cygwinb19.dll to avoid invalidating +previously built executables. + +Note that a B19-compiled application exec()ing a B18-compiled +application will treat the B18-compiled executable as an ordinary +Win32 executable. This means that open file descriptors and some other +internals will not be inheritted on exec() calls. The reason for this +is that different shared memory areas are used by the different versions +of the cygwin library. This may or may not be of importance to you +depending on what you're doing. + +The Beta 19 release of the Cygwin32 library continues to be licensed +under the GNU General Public License (GPL). + +The PE format definition used by the compiler tools now matches +Microsoft's more closely. This should allow better interoperability +with other vendors' development tools although more work probably +remains to be done in this area. This change invalidates all previously +built object (.o) and static library (.a) files so be sure to +delete/rebuild old .o and .a files you are using! + +Finally, old symlinks are invalidated by this release. The "system" +attribute is now used to mark symlinks which significantly speeds +up fstat and other file related calls. Either recreate old ones or +set their "system" attribute flag so they will be recognized properly. + +The new installer takes care of all environment variable settings +automatically by installing a shortcut in program files that pulls +up a bash prompt with all the correct environment variables set. +As a result, the setup process should be much cleaner than in the last +release. + +For those of you who end up moving the tools around, the batch file +that sets up the default environment is called cygnus.bat and is +installed in the root of the install directory. Because the tools have +been compiled to install in /cygnus/b19, when installed in this +location, the tools should "just work" if the bin directory is in your +path (no special environment variables are needed). The only exception +is MAKE_MODE which needs to be set if you want to get ordinary Unix-like +make behavior -- see the make notes below for more information. + +@subsection Changes in specific tools: + +Ian Lance Taylor has written a resource compiler called "windres". +It can be used to compile windows resources from a textual rc file +into a COFF file. The sources are in the binutils subdirectory of +the sources. + +We have upgraded many of the utilities. Beta 19 includes bash 2.01.1, +fileutils 3.16, gawk 3.0.3, patch 2.5, shellutils 1.16, tar 1.12, +textutils 1.22, and texinfo 3.11. Bash under Cygwin32 now includes +working job control among other improvements. + +The sh executable is now ash 0.2 from the Debian Linux distribution. +Using this more minimal shell as /bin/sh.exe speeds up configures +significantly. + +Bison 1.25 has been added. + +Tcl/tk are upgraded to version 8.0. Compatible versions of tix and +itcl have been added. These all include Cygwin32-compatible configury +files so you can do a Unix-style build of the Win32 ports of tcl/tk. + +Expect 5.21.3 is included and basically works. + +The binaries have been compiled with i686 optimizations turned on +which may result in a speed increase on Pentium-based systems +although the tools should work on i386 and later chips. + +The linker (ld) has been enhanced -- it will now add the idata3 +terminator automatically when linking dlls. + +kill now supports signal names in arguments. ps now shows process +start time information. + +Although the default install of the tools should hide this detail, the +make utility now defaults to a Win32 mode which uses cmd.exe/command.com +as the subshell. This mode allows the use of backslashes in filenames. +To build Unix programs, you need to set the MAKE_MODE environment +variable to "UNIX". This way you will get the old behavior of using +sh.exe as the subshell. + +@subsection Changes in the Cygwin32 API (cygwin.dll): + +The interface is now better defined. It contains libc, libm, and +Unix compatability calls. It no longer contains exports for libgcc.a. +This should result in a more stable interface. See the calls.texinfo +document for interface documentation. + +There is now only one environment variable called CYGWIN32 that controls +the overall behavior of the dll: + + set CYGWIN32=[no]title [no]strip_title [no]binmode [no]glob + strace=mask:cache,file [no]tty + +So if you "set CYGWIN32=title tty", then you would get tty support +(see below) and have the current running process listed in the title +bar. + +B19 adds support for: + +* tty and pseudo-tty devices. For now, ttys default to off because +taking over the console causes problems with using non-Cygwin console +programs in a Cygwin console. To turn it on, set the environment +variable CYGWIN32 to include "tty". +* Hard links (requires NT on an NTFS filesystem). When not possible (on +non-NTFS filesystems), link() will make a copy of the file in question +as it has done in previous releases. +* The SIGWINCH signal. If tty handling is enabled then the process will +receive a SIGWINCH signal when the screen size changes. +* Additional terminal escape sequences recognized: scroll region setting via +<ESC>[n1;n2r and setting the console title using xterm escape sequence: +<ESC>]2;new title^G . + +The following calls have been added: + +* ptsname, grantpt, unlockpt +* login, logout, ttyslot, ctermid +* cfgetispeed, cfgetospeed, cfsetispeed, cfsetospeed +* setitimer, getitimer, ftime, tzset +* wait3, wait4, pause, sigpause +* getpgid, killpg, setegid (stub) +* strlwr, strupr +* sexecve, sexecl, sexecle, sexeclp, sexeclpe, sexecv, sexecp, sexecvpe +* rcmd, rresvport, rexec +* strsignal, strtosigno +* dlopen, dlsym, dlclose, dlerror +* inet_netof, inet_makeaddr +* socketpair +* fpathconf, realpath, chroot (stub) +* initgroups (stub), getgroups +* random, srandom + +The following calls have been removed: + +* ScreenCols, ScreenGetCursor, ScreenRows, ScreenSetCursor +* getkey, kbhit +* crypt (stub) +* all libgcc.a exports + +The Winsock dll (wsock32.dll) is no longer implicitly linked into +the Cygwin32 dll. Instead, it is explicitly loaded with LoadLibrary +the first time a process calls a Cygwin32 networking function. This +speeds up most processes significantly (configures by about 20%). + +The signal-related code has been rewritten from scratch. Ditto for +most of the path handling code. + +The globbing and getopt code has been replaced with BSD-derived +code. The regexp code has been replaced with Henry Spencer's PD +implementation. + +Doug Lea's malloc is now being used as the default malloc exported by +cygwin. This malloc balances speed and compactness very nicely but is +more unforgiving when attempts are made to free already freed memory, +i.e., a segmentation violation will occur. + +The bsearch call has been rewritten. + +Alt Gr-key behavior has been changed in this release. The left alt-key +still produces ESC-key sequence. The right alt (Alt Gr)-key now +produces characters according to national keyboard layouts. + +Processes no longer write their name in the title bar unless you include +"title" in the CYGWIN32 environment variable (see above). + +Multiple cygwin.dlls no longer use the same memory space unless they are +identical (built at the same time). This allows multiple dlls with +incompatible shared memory usage to be run simultaneously. It also +facilitates debugging a buggy cygwin.dll. By keeping only a single copy +of the latest cygwin.dll on your system, you can be assured of having +all cygwin processes exist in the same shared memory space. + +The slash mount no longer defaults to C:. It now defaults to the +system drive letter (where the OS is installed). + +The standard dl* dynamic library loader functions are now available. +Cygwin32 B19 now correctly copies data after a fork and automatically +reloads any DLLs loaded in the parent process. In addition, dlls will +now be correctly initialized when loaded and global constructors will +be called. Global destructors will be called when the DLL is detached. +Handles gotten from dlopen or dlsym in the parent will be accessible in a +forked child. The LD_LIBRARY_PATH environment variable is used in the dlopen +search. + +Include the file <cygwin32/cygwin_dll.h> in a cygwin32 created .dll and +use the line DECLARE_CYGWIN_DLL(dll-entry-point) to produce .dlls that +can be used with these functions. + +@section Release Beta 18 (May 6 1997) + +This is a major release. The new cygwin.dll is still +backwards-compatible with previously linked applications but +contains significant changes. + +We have completely changed the installation process to make +use of an InstallShield5-based installer. This should reduce the +number of installation problems people have experienced in the +past. However, it is still necessary to set environment variables +by hand, as explained in the README.txt accompanying the distribution. +(Future gnu-win32 installers may include the capability to do this +automatically). + +@subsection Changes in specific tools: + +GCC compilation times have been improved by 20-30% by using spawn() +instead of fork(). + +GCC accepts both Win32 and POSIX paths/path lists in its +environment variables (COMPILER_PATH, LIBRARY_PATH, C_INCLUDE_PATH, +CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH) + +GDB comes with a tcl/tk-based GUI (gdbtk). You can still invoke the +command line gdb by invoking it with "gdb -nw". + +Bash verifies that /tmp exists and is a directory upon startup. +It complains if this isn't the case. + +Running gcc or ld with "-s" used to create invalid executables. +The bug in bfd that was responsible for this has been fixed. + +The conflict between String.h and string.h (and other such pairs +of header files) where you include one and get the other has been +fixed. + +The top level install-sh script tries to install foo.exe if asked +to install foo when foo's not present. This fixes many installs +of Unix software. + +Dlltool has preliminary support for the IMPORT declaration in .def files +when invoked with -I. Feel free to experiment with it but once this +functionality is tested more extensively this flag may go away. + +Time is upgraded to version 1.7. + +Make is upgraded to version 3.75. + +Make accepts both Win32 and POSIX path lists in the VPATH variable. + +@subsection Changes in the Cygwin32 API (cygwin.dll): + +The following is now supported: + +* UNC paths +* Reverse index escapes in console code +* Blocking select()s on a combination of sockets/handles +* Directory symlinks. +* Reparenting of child processes. + +The following calls have been added: + +* mmap(), mprotect(), msync(), munmap(). fork() changed to support these. +* fsync(), statfs(), fstatfs(). +* getprotobynumber() and getservbyport(). +* get_osfhandle(), cwait(). +* spawnl(), spawnle(), spawnlp(), spawnlpe(), spawnv(), spawnve(), +spawnvp(), spawnvpe(). +* nice(). +* sigpending(), sigsuspend() +* Under NT only, chown(), getgrgid(), getgrnam(), endgrent(), getgrent(), +setpwend(), getpwent(), endpwent(). Win95 still has these as stubs. + +Significantly better signals / exception handling support added. +The kill signal works much better now (control-C works in bash). + +Shell scripts now run the shell specified after the #! instead of +always defaulting to /bin/sh. + +Floating point registers are now properly initialized in the crt0.o. + +Opening non-disk files such as com ports no longer check to see +if they are symlinks or executables. + +The console title now is set to the name of the running process. + +Winsock is now initialized upon app startup. + +Moved reent_data from private address space to cygwin.dll. + +The system() call now invokes spawnvp() instead of fork()/exec(). + +Support for NT extended attributes has been added but is disabled +for now because it slowed things down too much. We want to use them to +remember info about symlink and executable status of files. + +Under NT only, utilities mkpasswd and mkgroup can generate a valid +/etc/passwd and /etc/group. + +Earlier releases stored mount points in the registry under +"Cygnus Support". This changed to "Cygnus Solutions" starting +with beta 18. Either use a registry editor (regedit under NT) +to rename the old entry or just redo your mount points and the +cygwin.dll will automatically create the new one for you. + +Mount points can now be up to MAX_PATH in length instead of 30 +characters. + +@section Release Beta 17.1 (Dec 10 1996) + +A patch has been applied to make Win 95 configure work again. + +ld has been changed to make "a.exe" be the default executable name. + +@section Release Beta 17 (Dec 7 1996) + +It is now possible to rebuild the tools natively under x86 NT when +the full Cygnus Developers' Kit (CDK) and the User Tools are both +installed correctly. + +While the cygwin.dll underwent substantial changes, none of them +prevent you from using previously built applications The new dll +is compatible with beta 16 to the best of our knowledge. Beta 14-built +programs will continue to fail with the beta 17 dll -- you will have to +relink them before they will work. + +The winsup files that make up the Cygwin32 API are now under the +GNU General Public License. See the accompanying press release +for more information. + +@subsection Changes in specific tools: + +Gcc now links by default against -lkernel32 and also against +-luser32 -lgdi32 -lcomdlg32 when mwindows is set. Another major +change is that when creating an executable, gcc will now create +foo.exe when given a -o argument of foo. + +Dlltool has patches to make it better handle the --subsystem argument +that allows choosing console vs. GUI among other options. +ld has been changed to have a much larger stack reserve size. This +is necessary when rebuilding the toolchain natively under NT. + +The C++ headers can now be found given a correctly set GCC_EXEC_PREFIX +environment variable. + +New versions of fileutils and make are included. Findutils has been +added. + +@subsection Changes in the Cygwin32 API (cygwin.dll): + +Scott Christley's headers and def files for the standard Win32 dlls +have been integrated. Anything present only in the previous Cygnus headers +has been added in the appropriate places. There are placeholder files +with the standard Win32 header names that pull in our headers so +programs that try to include specific headers should continue to work. +Having more complete headers should make Win32 native programming +easier. + +Select has been rewritten from scratch. The new one can deal with +all sockets, handles and sockets always ready, all handles. Handles +and sockets with timeout not implemented yet. Select now does +blocking and doesn't spin cpu. + +File handling has been largely rewritten: +The fhandler array has been moved into local memory instead of shared +memory. This makes a number of things behave better. Lots of changes +to support this. There is now fairly complete ansi/vt100 console support. +Some new file locking support has been added. Arrow keys are now +supported. + +Process handling much improved. + +Significant serious bugs in fork() fixed. + +The system() call now works. + +unlink() now chmods read-only files to writable before attempting to +delete a file. This fixes the outstanding problem where rm can't +delete read-only files saying "out of queue slots" repeatedly. + +Text mode read has been rewritten. + +New syslog code allows logging to event log under NT, file under Win 95. + +Symlinks are enabled. + +readv() and writev() have been written and exported. + +For MS compatibility, we now export functions in the dll as _funcname +in addition to funcname. I would suggest not making use of this fact +unless you are building code that already accesses C library calls +in this way. + +Almost all of the source code is now in C++ files. + +@section Release Beta 16 (Aug 30 1996) + +Path handling has been completely rewritten. To refer to drive Q: in +bash, you can now refer to //q/. Alternatively, type "mount Q: /q" to +have drive Q: show up as /q. + +We now pass the Plum Hall positive C conformance tests on the +i386 under Windows 95 and NT 4.0b2. + +Fork was previously not accessible inside the dll. This is no +longer the case which should allow us to add working system and popen +calls. + +getdomainname works (it used to just return "cygnus.com") by getting +information from registry. + +Fixed readdir bug that set errno improperly. This fixed the problem +with diff not working across directories. + +Better error checking in signal functions. Initialize winsock in +cygwin32_socket with checkinit call (fixes bug that required calling any +function that did this first). + +New functions: sigaddset, sigismember, sigfillset, sigemptyset. + +Removed extra underscores present in sysdef files. + +There is a now a major and a minor version number associated with +the cygwin.dll. The major number changes only when incompatible changes +are made, the minor number changes when significant changes are made +to the dll that don't require relinking of old apps. + +Changed value of HZ in include/sys/param.h to correct value of 1000. +(Fixes bug people reported about "time sleep 5" returning 50). + +Assorted exception handling fixes for both i386 and ppc processors. + +Assorted time-related fixes required for Cygnus Kerberos work. +New time functions: gmtime, corelocaltime + +Assorted spawn and fork fixes. + +Pseudo-Unix process handling added -- new ps and kill commands added + +Control-Z's are now handled as a valid EOF token in files opened as +text. +lseek now always operates in binary mode. + +Select revamped. + +Various other changes. For more detailed information, consult the file +in the source code winsup/ChangeLog. + +Preprocessor define scheme changed. Apps should now use _WIN32 +instead of __WIN32__ to check for access to Win32 API and __CYGWIN32__ +to check for presence of the Cygwin32 environment. + +We are no longer including GNU findutils, GNU dbm, GNU bison, +GNU less, ncurses, ftp, finger, rcl, cvtres, or V. This may or may not +change in the future. + +You must relink old apps you built with prior releases with the new +cygwin.dll. + +@section Release Beta 14 (April 10 1996) + +Some bugs have been fixed. GDBM and m4 are in the release. GCC now +uses the standard install directories for cc1 etc. + +A port of V to gnu-win32 is included. You can now write graphics +applications which will run on Unix or Windows unchanged. Some parts of +V work on the PPC too. + +If you call any programs from the standard DOS shell, then the DLL will +expand all the wildcards (glob) found in the arguments on the command +line. So ls *.exe will do what you think it should, even if you're not +in bash. + +ncurses and less are included. The DLL's emulation of a vt100 isn't complete, +so ncurses doesn't do all that it should. Hence less is more or less +useless. This can be fixed with a new DLL. (If you want to use +something which uses curses, be sure to set your TERM and HOME +envirionment variables) + +If you leave out main, then the libraries will try and call WinMain in the +usual way. + +^C works much better on Windows 95. It's still not quite right, but at +least most times it quits what you're doing, and most times doesn't +crash your machine. + +You can start more than one concurrent bash session. + +Some networking support has been added. Even though telnet.exe is provided, +I know that it doesn't work, so please don't send me bug reports. + +You will have to relink your applications to go with the new DLL. + +The DLL is released in its own .zip file too, so you don't have to +download a load of other stuff if you dont want to. + +@section Release Beta 13 (Feb 9 1996) + +Files are opened in binary mode, unless the registry is fiddled with. + +The `cat >foo <<EOF bug is fixed. + +The symlink cookie has changed, so old links wont work any more. + +Two resource tools are provided (untested). + +More windows header files are provided. WxWindows almost compiles. + +You can get to a raw floppy with `/dev/fd0 or `/dev/fd1. + +You can have two filenames with the same name and different case in +the same directory. + +Stat now fills in the st_nlink field for directories, so find works +better. + +This version is much more stable than any previous version, and will +stay running long enough to configure and build itself on my NT box. + +This version is also available in PowerPC versions. The PowerPC +compiler doesn't do stack probing, so some applications won't work, or +they'll only work on some input data - e.g. the demo "hello world" will +compile, but gcc will crash compiling the dhrystone benchmark. + +There's a new registry variable "fmode=binary" which controls +whether the tools always open files in binary mode (unless overridden +with O_TEXT), or always open files in text mode (unless overridden with +O_BINARY). + +Filesystems can be mounted with the mixed_case flag. This allows +you to use filenames with the same spelling, but different case in the +same directory. + +I haven't tested or even used some of the packages that I've +provided. I compiled them, and then fixed the obvious "the file should +have been opened in binary mode" problems. + +I've already had reports of some of it not working correctly on +Windows 95. I don't have a simple to use Windows 95 configuration, but +when I did try "it worked for me". This may be another manifestation +of the bug which makes bash hang sometimes under NT. + +@section Release Beta 12 (Jan 3 1996) + +You can call non- gnu-win32 applications from bash. + +You can mount other directories using the @code{mount} command. + +Minimal ANSI terminal emulation included. + +Packages split into smaller and more logical lumps. + +/d<name> mechanism gone. + +Initial support for the PowerPC added. + +@section Release Beta 11 (Jan 3 1996) + +Something broke on the way to the ftp site. + +@section Release Beta 10 (Dec 5 1995) + +You can pass environment variables around in bash. + +Lots more stuff provided precompiled. + +Diffs to standard FSF release provided. + +It self-hosts. + +It supports symbolic links. + +The directory layout has changed to be more unix like. + +The way that you get to non-c drives is new - i:\foo.cc +is now /di/foo.cc + +Nasty bug found and fixed in fork. + +CPP will now search the directories you supply in env names. + +@section Release Beta 9 + +I've put all of libc and libm into a shared library, +This drastically reduces the size of some binaries. +e.g., ls goes from 82,949 bytes to 26,624. +"Hello World" is 2564 bytes long. +This is the first stage in greatly speeding up +some of the stuff that's going on behind the curtain. + +Different processes communicate using shared memory. + +Some trivial use of the registry is made. + +DLLTOOL is now *much* faster. + +Some small problems have been fixed in the way that DLLs were +layed out. + +@section Release Beta 8 + +GDB works. + +GCC now emits debug info which can make **huge** executables +Fortunately, strip works too. + +More work has been done to make quoting work. + +Simple termios support added to newlib. + +Much nicer way of describing paths, eg //c/foo is c:\foo. + +@section Release Beta 7 + +Works again on Win 95 (which is why -6 wasn't advertised). + +Permissions are faked better. + +Source of demos available without having to ftp the entire win32 +binary tree. + +@section Release Beta 6 + +Can now generate DLLs, tiny demo included. +tcl, byacc, fileutils, diff, make included. + +@section Release Beta 5 + +Bug preventing anything from running on recent versions +of Win95 fixed. + +vfork and exec oddities fixed. + +Import libraries are now really libraries and not +just .o files. + +Debugging info stripped from images and libraries; +it's just bloat until gdb works. + +I've filled in the four major import libraries. + +The win*.h files are now installed into <foo>/include +rather that <foo>/include/sys, so more things will +compile out of the box. + +@section Release Beta 4 + +PE support is fixed. Programs run on +NT 3.1, NT 3.5, NT 3.51 and Windows 95. + +You can build GUI programs. + +.DEF files for three other DLL's started. + +New GUI demo program. + +C library distinguishes between text and binary files +consequently the text files generated by the +tools have the familiar ^M at the end of the line +which DOS likes so much. + +Doug Evans of Cygnus has added a load +of fancy support for execve, opendir and +various other cool things. + +Exception handling is better. + +@section Release Beta 3 + +Was so long ago we don't remember. diff --git a/winsup/doc/how.texinfo b/winsup/doc/how.texinfo new file mode 100644 index 000000000..9d8c405f1 --- /dev/null +++ b/winsup/doc/how.texinfo @@ -0,0 +1,1140 @@ +@chapter Question and Answers + +@section Where can I get more information? + +@subsection Where's the documentation? + +There are links to quite a lot of it on the main Cygwin project WWW page: +@file{http://sourceware.cygnus.com/cygwin/} +Be sure to at least read the Release Notes on the main WWW page, if +there are any. + +Tool-specific documentation is available at: +@file{http://www.cygnus.com/pubs/gnupro/} + +@subsection What Cygwin mailing lists can I join? + +To subscribe to the main list, send a message to +cygwin-subscribe@@sourceware.cygnus.com. To unsubscribe from the +main list, send a message to cygwin-unsubscribe@@sourceware.cygnus.com. +In both cases, the subject and body of the message is ignored. + +Similarly, to subscribe to the Cygwin annoucements list, send a message +to cygwin-announce-subscribe@@sourceware.cygnus.com. To unsubscribe, +send a message to cygwin-announce-unsubscribe@@sourceware.cygnus.com. + +If you are going to help develop the Cygwin library by volunteering for +the project, you will want to subscribe to the Cygwin developers list, +called cygwin-developers. The same mechanism as described for the first +two lists works for this one as well. + +There's an archive of the main mailing list at + +@file{http://sourceware.cygnus.com/ml/cygwin/} + +@subsection Why won't you/the mailing list answer my questions? + +Perhaps your question has an answer that's already in the FAQ. +Perhaps nobody has time to answer your question. Perhaps nobody +knows the answer... + +@section Installation and Setup + +@subsection Why is the install of the tools failing? + +If you are getting an error message saying "The decompression of +%s failed. There may not be enough free disk space in the TEMP +directory.", read on. + +InstallShield has a bug where it fails with this message if there +are more than a certain number of files in your TEMP directory. +You can also get this message if you have files in your TEMP dir +named the same thing InstallShield wishes to name its files (probably +from past runs of other InstallShield install scripts) which it cannot, +for some reason, write over. Perhaps this will be fixed in a future +release of InstallShield. + +Until then, clearing out your TEMP directory entirely should do it. +That will get rid of any files with conflicting names and solve the +"too many files" problem as well. + +@subsection Help! I haven't created /tmp and tools are behaving strangely! + +Many Unix tools (bash, byacc, etc.) expect that /tmp always exists. +This is not guaranteed in Win32 land. You should create /tmp or "mount" +the directory of your choice to /tmp to avoid this problem. + +@subsection Why does bash spew out "49054596: No such file or directory"? + +Are you sure you created a /tmp? The bash shell will print a +warning if it doesn't find a /tmp directory. + +@subsection How do I set /etc up? + +If you want a valid /etc set up (so "ls -l" will display correct +user information for example) and if you are running NT (preferably +with an NTFS file system), you should just need to create the /etc +directory on the filesystem mounted as / and then use mkpasswd and +mkgroup to create /etc/passwd and /etc/group respectively. Since +Windows 95/98's Win32 API is less complete, you're out of luck if +you're running Windows 95/98. + +@subsection Bash says that it can't vfork (or just hangs). Why? + +Most often this is because it can't find itself in the path. Make sure +that your path includes the directory where bash lives, before you start +it. + +Also make sure you have a valid @code{/bin/sh.exe}. If you get errors +like 'no such file or directory' when you're trying to run a shell +script, which you know is there, then your problem is probably that bash +can't find @code{/bin/sh}. + +@subsection How can I get bash to read my .bashrc file on startup? + +Your .bashrc is read from your home directory specified by the HOME +environment variable. It uses /.bashrc if HOME is not set. So you need +to set HOME correctly, or move your .bashrc to the top of the drive +mounted as / in Cygwin. + +@subsection How can I get bash filename completion to be case insensitive? + +"shopt -s nocaseglob" should do the trick. + +@subsection Can I use paths/filenames containing spaces in them? + +Cygwin does support spaces in filenames and paths. That said, some +utilities that use the library may not, since files don't typically +contain spaces in Unix. If you stumble into problems with this, you +will need to either fix the utilities or stop using spaces in filenames +used by Cygwin tools. + +@subsection Why can't I cd into a shortcut to a directory? + +Cygwin does not follow MS Windows Explorer Shortcuts (*.lnk +files) yet. It sees a shortcut as a regular file and this you +cannot "cd" into it. + +Some people have suggested replacing the current symbolic link scheme +with shortcuts. The major problem with this is that .LNK files would +then be used to symlink Cygwin paths that may or may not be valid +under native Win32 non-Cygwin applications such as Explorer. + +@subsection I'm having basic problems with find. Why? + +Make sure you are using the find that came with the Cygwin tools +and that you aren't picking up the Win32 find command instead. You +can verify that you are getting the right one by doing a "type find" +in bash. + +@subsection Why don't cursor keys work under Win95/Win98? + +Careful examination shows that they not just non-functional, but +rather behave strangely, for example, with NumLock off, keys on numeric +keyboard work, until you press usual cursor keys, when even numeric +stop working, but they start working again after hitting alphanumeric +key, etc. This reported to happen on localized versions of Win98 and +Win95, and not specific to Cygwin (there're known cases of Alt+Enter +(fullscreen/windowed toggle) not working and shifts sticking with +other programs). The cause of this problem is Microsoft keyboard +localizer which by default installed in 'autoexec.bat'. Corresponding +line looks like: + +@example +keyb ru,,C:\WINDOWS\COMMAND\keybrd3.sys +@end example + +(That's for russian locale.) You should comment that line if you want +your keys working properly. Of course, this will deprive you of your +local alphabet keyboard support, so you should think about +another localizer. exUSSR users are of course knowledgable of Keyrus +localizer, and it might work for other locales too, since it has keyboard +layout editor. But it has russian messages and documentation ;-( +Reference URL is http://www.hnet.ru/software/contrib/Utils/KeyRus/ +(note the you may need to turn off Windows logo for Keyrus to operate +properly). + +@subsection Is it OK to have multiple copies of the DLL? + +It's a bad idea to have multiple versions of the cygwin DLL in +your path. They often conflict in funny ways. If you have +multiple versions, it's usually OK to get rid of (or rename) +all the older versions, keeping only the newest one. + +It should be OK to have multiple copies of the *same* DLL +in your path, though. + +@section Using Cygwin Releases + +@subsection Why aren't man, groff, etc. included in the betas? + +For obvious reasons, it isn't feasible for us to maintain and provide +binary distributions of every tool ported to work with the Cygwin +tools. However, it's likely that a man command will show up in a +distribution soon. + +Many other tools have been ported and are referenced on the Cygwin web +site. man, groff, info, and many many other packages are all +available for download there. + +@subsection Where can I find "less"? + +The less pager binary is available for the first time in the 20.1 +release. You will get it if you upgrade. It is also available from +various ftp locations on the Net. Search the mailing list archives for +the details. + +@subsection Where can I find "more"? + +If you are looking for the "more" pager, you should use the "less" pager +instead. See the last question and answer for more information. + +@subsection Where can I find "which"? + +While we don't include a which command, you can use the bash built +in "type" command which does something fairly similar. + +@subsection How can I access other drives? + +The best way is to use the "mount" command to mount the drive letter so +that you can refer to it with only single slashes: + +@example +bash$ mkdir /c +bash$ mount c:/ /c +bash$ ls /c +.... +@end example + +This is done with textual substitution whenever a file is opened. +So if you're going to do @code{ls /c/bar} on a mount like the above +the guts will turn that into @code{ls c:/bar}. + +Note that you only need to mount drives once. The mapping is kept +in the registry so mounts stay valid pretty much indefinitely. +You can only get rid of them with umount (or the registry editor). + +The '-b' option to mount mounts the mountpoint in binary mode where text +and binary files are treated equivalently. This should only be +necessary for badly ported Unix programs where binary flags are missing +from open calls. + +Since the beta 16 release, we also support a special means of accessing +other drive letters without using the @code{mount} command. This +support may disappear in a future Cygwin release because of the +collision between this scheme and UNC pathname support (one character +machine names don't work currently). + +To do an "ls" on drive letter f:, do the following: + +@example +bash$ ls //f/ +@end example + +Note that you can also access UNC paths in the standard way. Because of +the drive letter shortcut mentioned above, machine names in UNC paths +must be more than one character long. + +@subsection How can I copy and paste into Cygwin console windows? + +Under Windows NT, open the properties dialog of the console window. +The options contain a toggle button, named "Quick edit mode". It must +be ON. Save the properties. + +Under Windows 9x, open the properties dialog of the console window. +Select the Misc tab. Uncheck Fast Pasting. Check QuickEdit. + +@subsection What does "mount failed: Device or resource busy" mean? + +This usually means that you are trying to mount to a location +already in use by mount. For example, if c: is mounted as '/' +and you try to mount d: there as well, you will get this error +message. First "umount" the old location, then "mount" the new one and +you should have better luck. + +If you are trying to umount '/' and are getting this message, you may +need to run @code{regedit.exe} and change the "native" key for the '/' +mount in one of the mount points kept under +HKEY_CURRENT_USER/Software/Cygnus Solutions/CYGWIN.DLL setup/<version> +where <version> is the latest registry version associated with the +Cygwin library. + +@subsection How can I share files between Unix and Windows? + +During development, we have both Unix boxes running Samba and +NT/Windows 95/98 machines. We often build with cross-compilers +under Unix and copy binaries and source to the Windows system +or just toy with them directly off the Samba-mounted partition. +On dual-boot NT/Windows 9x machines, we usually use the FAT +filesystem so we can also access the files under Windows 9x. + +@subsection Are mixed-case filenames possible with Cygwin? + +Several Unix programs expect to be able to use to filenames +spelled the same way, but with different case. A prime example +of this is perl's configuration script, which wants @code{Makefile} and +@code{makefile}. WIN32 can't tell the difference between files with +just different case, so the configuration fails. + +In releases prior to beta 16, mount had a special mixed case option +which renamed files in such a way as to allow mixed case filenames. +We chose to remove the support when we rewrote the path handling +code for beta 16. + +@subsection What about DOS special filenames? + +Files cannot be named com1, lpt1, or aux (to name a few); either as +the root filename or as the extension part. If you do, you'll have +trouble. Unix programs don't avoid these names which can make things +interesting. E.g., the perl distribution has a file called +@code{aux.sh}. The perl configuration tries to make sure that +@code{aux.sh} is there, but an operation on a file with the magic +letters 'aux' in it will hang. + +@subsection When it hangs, how do I get it back? + +If something goes wrong and the tools hang on you for some reason (easy +to do if you try and read a file called aux.sh), first try hitting ^C to +return to bash or the cmd prompt. + +If you start up another shell, and applications don't run, it's a good +bet that the hung process is still running somewhere. Use the Task +Manager, pview, or a similar utility to kill the process. + +And, if all else fails, there's always the reset button/power switch. +This should never be necessary under Windows NT. + +@subsection Why the weird directory structure? + +Why are cpp.exe, cc1.exe, etc., not in the bin directory? + +Why more than one lib and include directory? + +@smallexample +H-i586-cygwin32\lib\gcc-lib\...\egcs-2.91.57\include +x86-cygwin32\include +x86-cygwin32\H-i586-cygwin32\i586-cygwin32\include +@end smallexample + +This way multiple releases for different hosts and targets can all +coexist in the same tree. H-i586-cygwin32 means hosted on +i586-cygwin32, common files shared by all hosts are in the top level +directories, target-specific files are in the +H-i586-cygwin32/i586-cygwin32 +directory, etc... + +If you had a server sharing files to a ppc NT machine and an x86 NT +machine, you could have both an H-i586-cygwin32 and an +H-powerpcle-cygwin32 directory without having to duplicate the top level +files that are the same for both hosts. If you built and installed an +i586-cygwin32 x mips-elf cross-compiler, you would have an +H-i586-cygwin32/mips-elf with its target-specific files and some +mips-elf- prefixed binaries in H-i586-cygwin32/bin. + +Normally we also have another higher level directory that identifies the +release. Then multiple Cygwin releases can coexist with different +dll versions, giving: + +@smallexample +cygnus/b19/H-i586-cygwin32 +cygnus/cygwin-b20/H-i586-cygwin32 +... +@end smallexample + +In any case, this does add complexity to the directory structure but +it's worth it for people with more complex installations. + +@subsection How do anti-virus programs like Cygwin? + +One person reported that McAfee VirusScan for NT (and others?) is +incompatible with Cygwin. This is because it tries to scan the +newly loaded shared memory in the cygwin.dll, which can cause fork()s +to fail, wreaking havoc on many of the tools. + +@subsection Why can't I run bash as a shell under NT Emacs? + +Place the following code in your startup file and try again: + +@smallexample +(load "comint") +(fset 'original-comint-exec-1 (symbol-function 'comint-exec-1)) +(defun comint-exec-1 (name buffer command switches) + (let ((binary-process-input t) + (binary-process-output nil)) + (original-comint-exec-1 name buffer command switches))) +@end smallexample + +@subsection Where did the man/info pages go? + +In order to save space and download times, we have stopped providing +the man/info files for the tools with the binary install since we are +not yet providing a man page or info reader. Both types of +documentation are available in a tar file available from the project ftp +site. Or consult the online documentation over the WWW. + +@subsection Why can't B20's "cygcheck -s" find cpp? + +This is a confusingly worded warning that will be reworded in future +versions. In fact, cygcheck should normally *not* find cpp; if it does, +it may be a problem (e.g. it might pick up Borland's cpp, which would +cause problems). + +@subsection Why do I get a message saying Out of Queue slots? + +"Out of queue slots!" generally occurs when you're trying to remove +many files that you do not have permission to remove (either because +you don't have permission, they are opened exclusively, etc). What +happens is Cygwin queues up these files with the supposition that it +will be possible to delete these files in the future. Assuming that +the permission of an affected file does change later on, the file will +be deleted as requested. However, if too many requests come in to +delete inaccessible files, the queue overflows and you get the message +you're asking about. Usually you can remedy this with a quick chmod, +close of a file, or other such thing. (Thanks to Larry Hall for +this explanation). + +@subsection Why don't symlinks work on samba-mounted filesystems? + +Symlinks are marked with "system" file attribute. Samba does not +enable this attribute by default. To enable it, consult your Samba +documentation and then add these lines to your samba configuration +file: + +@smallexample + mask system = yes + create mask = 0775 +@end smallexample + +Note that the 0775 can be anything as long as the 0010 bit is set. + +@subsection Why does df report sizes incorrectly. + +There is a bug in the Win32 API function GetFreeDiskSpace that +makes it return incorrect values for disks larger than 2 GB in size. +Perhaps that may be your problem? + +@subsection Has the screen program been ported yet? + +Screen requires either unix domain sockets or fifoes. Neither of +them have been implemented in Cygwin yet. + +@section Cygwin API Questions + +@subsection How does everything work? + +There's a C library which provides a Unix-style API. The +applications are linked with it and voila - they run on Windows. + +The aim is to add all the goop necessary to make your apps run on +Windows into the C library. Then your apps should run on Unix and +Windows with no changes at the source level. + +The C library is in a DLL, which makes basic applications quite small. +And it allows relatively easy upgrades to the Win32/Unix translation +layer, providing that dll changes stay backward-compatible. + +For a good overview of Cygwin, you may want to read the paper on Cygwin +published by the Usenix Association in conjunction with the 2d Usenix NT +Symposium in August 1998. It is available in html format on the project +WWW site. + +@subsection Are development snapshots for the Cygwin library available? + +Yes. They're made whenever anything interesting happens inside the +Cygwin library (usually roughly on a nightly basis, depending on how much +is going on). They are only intended for those people who wish to +contribute code to the project. If you aren't going to be happy +debugging problems in a buggy snapshot, avoid these and wait for a real +release. The snapshots are available from +http://sourceware.cygnus.com/cygwin/snapshots/ + + +@subsection How is the DOS/Unix CR/LF thing handled? + +Let's start with some background. + +In UNIX, a file is a file and what the file contains is whatever the +program/programmer/user told it to put into it. In Windows, a file is +also a file and what the file contains depends not only on the +program/programmer/user but also the file processing mode. + +When processing in text mode, certain values of data are treated +specially. A \n (new line) written to the file will prepend a \r +(carriage return) so that if you `printf("Hello\n") you in fact get +"Hello\r\n". Upon reading this combination, the \r is removed and the +number of bytes returned by the read is 1 less than was actually read. +This tends to confuse programs dependant on ftell() and fseek(). A +Ctrl-Z encountered while reading a file sets the End Of File flags even +though it truly isn't the end of file. + +One of Cygwin's goals is to make it possible to easily mix Cygwin-ported +Unix programs with generic Windows programs. As a result, Cygwin opens +files in text mode as is normal under Windows. In the accompanying +tools, tools that deal with binaries (e.g. objdump) operate in unix +binary mode and tools that deal with text files (e.g. bash) operate in +text mode. + +Some people push the notion of globally setting the default processing +mode to binary via mount point options or by setting the CYGWIN32 +environment variable. But that creates a different problem. In +binary mode, the program receives all of the data in the file, including +a \r. Since the programs will no longer deal with these properly for +you, you would have to remove the \r from the relevant text files, +especially scripts and startup resource files. This is a porter "cop +out", forcing the user to deal with the \r for the porter. + +It is rather easy for the porter to fix the source code by supplying the +appropriate file processing mode switches to the open/fopen functions. +Treat all text files as text and treat all binary files as binary. +To be specific, you can select binary mode by adding @code{O_BINARY} to +the second argument of an @code{open} call, or @code{"b"} to second +argument of an @code{fopen} call. You can also call @code{setmode (fd, +O_BINARY)}. + +Note that because the open/fopen switches are defined by ANSI, they +exist under most flavors of Unix; open/fopen will just ignore the switch +since they have no meaning to UNIX. + +Also note that @code{lseek} only works in binary mode. + +Explanation adapted from mailing list email by Earnie Boyd +<earnie_boyd@@yahoo.com>. + +@subsection Is the Cygwin library multi-thread-safe? + +No. + +There is an experimental configure option (--enable-threadsafe), which +allows you to build a DLL with some additional "thread safety" but there +are no guarantees that this is 100% operational. This option also +enables limited "POSIX thread" support. See the file cygwin.din for the +list of POSIX thread functions provided. + +Cygnus does not distribute a DLL with this option enabled, and, +currently, has no plans to do so. + +Cygwin is not multi-thread-safe because: + +1) Newlib (out libc/libm) isn't reentrant (although it almost is). +This would have to be fixed or we would have to switch to a libc/libm +that is reentrant. + +2) Cygwin locks shared memory areas (shared by multiple processes), +but the per-process data is not locked. Thus, different threads in a +multi-threaded application would have access to it and give rise to +nasty race-conditions. + +The Mingw package (what you get when you invoke gcc with -mno-cygwin) is +multi-thread-safe because that configuration doesn't use Cygwin or +newlib. Instead, it uses Microsoft libraries which are +multi-thread-safe for the most part. So as long as the programmer +avoids Microsoft APIs that aren't multi-thread-safe (most are ok), they +should be fine. + +@subsection Why is some functionality only supported in Windows NT? + +Windows 9x: n. +32 bit extensions and a graphical shell for a 16 bit patch to an +8 bit operating system originally coded for a 4 bit microprocessor, +written by a 2 bit company that can't stand 1 bit of competition. + +But seriously, Windows 9x lacks most of the security-related calls and +has several other deficiencies with respect to its version of the Win32 +API. See the calls.texinfo document for more information as to what +is not supported in Win 9x. + +@subsection How is fork() implemented? + +Cygwin fork() essentially works like a non-copy on write version +of fork() (like old Unix versions used to do). Because of this it +can be a little slow. In most cases, you are better off using the +spawn family of calls if possible. + +Here's how fork works as of beta 18: + +Parent initializes a space in the Cygwin process +table for child. Parent creates child suspended using Win32 CreateProcess +call, giving the same path it was invoked with itself. Parent +calls setjmp to save its own context and then sets a pointer to this +in the Cygwin shared memory area (shared among all Cygwin tasks). +Parent fills in the childs .data and .bss subsections by copying from +its own address space into the suspended child's address space. +Parent then starts the child. Parent waits on mutex for child to get +to safe point. Child starts and discovers if has been forked and +then longjumps using the saved jump buffer. Child sets mutex parent +is waiting on and then blocks on another mutex waiting for parent to +fill in its stack and heap. Parent notices child is in safe area, +copies stack and heap from itself into child, releases the mutex +the child is waiting on and returns from the fork call. Child wakes +from blocking on mutex, recreates any mmapped areas passed to it via +shared area and then returns from fork itself. + +@subsection How does wildcarding (globbing) work? + +If an application using CYGWIN.DLL starts up, and can't find the +@code{PID} environment variable, it assumes that it has been started +from the a DOS style command prompt. This is pretty safe, since the +rest of the tools (including bash) set PID so that a new process knows +what PID it has when it starts up. + +If the DLL thinks it has come from a DOS style prompt, it runs a +`globber' over the arguments provided on the command line. This means +that if you type @code{LS *.EXE} from DOS, it will do what you might +expect. + +Beware: globbing uses @code{malloc}. If your application defines +@code{malloc}, that will get used. This may do horrible things to you. + +@subsection How do symbolic links work? + +CYGWIN.DLL generates link files with a magic header. When +you open a file or directory that is a link to somewhere else, it +opens the file or directory listed in the magic header. Because we +don't want to have to open every referenced file to check symlink +status, Cygwin marks symlinks with the system attribute. Files +without the system attribute are not checked. Because remote samba +filesystems do not enable the system attribute by default, symlinks do +not work on network drives unless you explicitly enable this +attribute. + +@subsection Why do some files, which are not executables have the 'x' type. + +When working out the unix-style attribute bits on a file, the library +has to fill out some information not provided by the WIN32 API. + +It guesses that files ending in .exe and .bat are executable, as are +ones which have a "#!" as their first characters. + +@subsection How secure is Cygwin in a multi-user environment? + +Cygwin is not secure in a multi-user environment. For +example if you have a long running daemon such as "inetd" +running as admin while ordinary users are logged in, or if +you have a user logged in remotely while another user is logged +into the console, one cygwin client can trick another into +running code for it. In this way one user may gain the +priveledge of another cygwin program running on the machine. +This is because cygwin has shared state that is accessible by +all processes. + +(Thanks to Tim Newsham (newsham@@lava.net) for this explanation). + +@subsection How do the net-related functions work? + +The network support in Cygwin is supposed to provide the Unix API, not +the Winsock API. + +There are differences between the semantics of functions with the same +name under the API. + +E.g., the select system call on Unix can wait on a standard file handles +and handles to sockets. The select call in winsock can only wait on +sockets. Because of this, cygwin.dll does a lot of nasty stuff behind +the scenes, trying to persuade various winsock/win32 functions to do what +a Unix select would do. + +If you are porting an application which already uses Winsock, then +using the net support in Cygwin is wrong. + +But you can still use native Winsock, and use Cygwin. The functions +which cygwin.dll exports are called 'cygwin_<name>'. There +are a load of defines which map the standard Unix names to the names +exported by the dll -- check out include/netdb.h: + +@example +..etc.. +void cygwin_setprotoent (int); +void cygwin_setservent (int); +void cygwin_setrpcent (int); +..etc.. +#ifndef __INSIDE_CYGWIN_NET__ +#define endprotoent cygwin_endprotoent +#define endservent cygwin_endservent +#define endrpcent cygwin_endrpcent +..etc.. +@end example + +The idea is that you'll get the Unix->Cygwin mapping if you include +the standard Unix header files. If you use this, you won't need to +link with libwinsock.a - all the net stuff is inside the dll. + +The mywinsock.h file is a standard winsock.h which has been hacked to +remove the bits which conflict with the standard Unix API, or are +defined in other headers. E.g., in mywinsock.h, the definition of +struct hostent is removed. This is because on a Unix box, it lives in +netdb. It isn't a good idea to use it in your applications. + +As of the b19 release, this information may be slightly out of date. + +@subsection I don't want Unix sockets, how do I use normal Win32 winsock? + +To use the vanilla Win32 winsock, you just need to #define Win32_Winsock +and #include "windows.h" at the top of your source file(s). You'll also +want to add -lwsock32 to the compiler's command line so you link against +libwsock32.a. + +@subsection What version numbers are associated with Cygwin? + +There is a cygwin.dll major version number that gets incremented +every time we make a new Cygwin release available. This +corresponds to the name of the release (e.g. beta 19's major +number is "19"). There is also a cygwin.dll minor version number. If +we release an update of the library for an existing release, the minor +number would be incremented. + +There are also Cygwin API major and minor numbers. The major number +tracks important non-backward-compatible interface changes to the API. +An executable linked with an earlier major number will not be compatible +with the latest DLL. The minor number tracks significant API additions +or changes that will not break older executables but may be required by +newly compiled ones. + +Then there is a shared memory region compatibity version number. It is +incremented when incompatible changes are made to the shared memory +region or to any named shared mutexes, semaphores, etc. + +Finally there is a mount point registry version number which keeps track +of non-backwards-compatible changes to the registry mount table layout. +This has been "B15.0" since the beta 15 release. + +@subsection Why isn't _timezone set correctly? + +Did you explicitly call tzset() before checking the value of _timezone? +If not, you must do so. + +@section Programming Questions + +@subsection Why is gcc failing? + +If the error is "gcc: installation problem, cannot exec `cpp': +No such file or directory", the GCC_EXEC_PREFIX environment variable +hasn't been set correctly. The current release does not need +GCC_EXEC_PREFIX set -- it should be able to find cpp regardless of the +install location. But if you have it set incorrectly, you may still +see this message. + +@subsection Why can't bison find bison.simple or bison.hairy? + +If you are getting a warning to this effect, you need to set +the BISONLIB environment variable. The value should be the directory +in which bison.simple and bison.hairy are installed. This will be +the path leading up to and including the @code{share} directory of +the top-level of the binary distributions. For example, on some +systems, you would want to set it to @code{C:/cygnus/cygwin-b20/share}. + +@subsection Why is make behaving badly? + +Starting with the beta 19 release, make defaults to a win32 mode in +which backslashes in filenames are permitted and cmd.exe/command.com +is used as the sub-shell. In this mode, escape characters aren't +allowed among other restrictions. For this reason, you must set +the environment variable MAKE_MODE to UNIX to run make on ordinary Unix +Makefiles. Here is the full scoop: + +MAKE_MODE selects between native Win32 make mode (the default) and +a Unix mode where it behaves like a Unix make. The Unix mode does +allow specifying Win32-style paths but only containing forward slashes +as the path separator. The path list separator character is a colon +in Unix mode. + +Win32 mode expects path separators to be either / or \. Thus no +Unix-style \s as escape are allowed. Win32 mode also uses +cmd.exe/command.com as the subshell which means "copy" and "del" +(and other shell builtins) will work. The path list separator +character is semi-colon in Win32 mode. People who want an nmake-like +make might want to use this mode but no one should expect Unix +Makefiles to compile in this mode. That is why the default b19 +install sets MAKE_MODE to UNIX. + +@subsection Why the undefined reference to "WinMain@@16"? + +Try adding an empty main() function to one of your sources. + +@subsection How do I use Win32 API calls? + +It's pretty simple actually. Cygwin tools require that you explicitly +link the import libraries for whatever Win32 API functions that you +are going to use, with the exception of kernel32, which is linked +automatically (because the startup and/or built-in code uses it). + +For example, to use graphics functions (GDI) you must link +with gdi32 like this: + +gcc -o foo.exe foo.o bar.o -lgdi32 + +or (compiling and linking in one step): + +gcc -o foo.exe foo.c bar.c -lgdi32 + +The following libraries are available for use in this way: + +advapi32 largeint ole32 scrnsave vfw32 +cap lz32 oleaut32 shell32 win32spl +comctl32 mapi32 oledlg snmp winmm +comdlg32 mfcuia32 olepro32 svrapi winserve +ctl3d32 mgmtapi opengl32 tapi32 winspool +dlcapi mpr penwin32 th32 winstrm +gdi32 msacm32 pkpd32 thunk32 wow32 +glaux nddeapi rasapi32 url wsock32 +glu32 netapi32 rpcdce4 user32 wst +icmp odbc32 rpcndr uuid +imm32 odbccp32 rpcns4 vdmdbg +kernel32 oldnames rpcrt4 version + +The regular setup allows you to use the option -mwindows on the +command line to include a set of the basic libraries (and also +make your program a GUI program instead of a console program), +including user32, gdi32 and, IIRC, comdlg32. + +Note that you should never include -lkernel32 on your link line +unless you are invoking ld directly. Do not include the same import +library twice on your link line. Finally, it is a good idea to +put import libraries last on your link line, or at least after +all the object files and static libraries that reference them. + +The first two are related to problems the linker has (as of b18 at least) +when import libraries are referenced twice. Tables get messed up and +programs crash randomly. The last point has to do with the fact that +gcc processes the files listed on the command line in sequence and +will only resolve references to libraries if they are given after +the file that makes the reference. + +@subsection How do I compile a Win32 executable that doesn't use Cygwin? + +The -mno-cygwin flag to gcc makes gcc link against standard Microsoft +DLLs instead of Cygwin. This is desirable for native Windows programs +that don't need a UNIX emulation layer. + +@subsection How do I make the console window go away? + +The default during compilation is to produce a console application. +It you are writing a GUI program, you should either compile with +-mwindows as explained above, or add the string +"-Wl,--subsystem,windows" to the GCC commandline. + +@subsection Why does make complain about a "missing separator"? + +This problem usually occurs as a result of someone editing a Makefile +with a text editor that replaces tab characters with spaces. Command +lines must start with tabs. + +@subsection Why can't we redistribute Microsoft's Win32 headers? + +Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks like +it says that can not "permit further redistribution of the +Redistributables to their end users". We take this to mean that we can +give them to you, but you can't give them to anyone else, which is +something that Cygnus can't agree to. Fortunately, we have our own +Win32 headers which are pretty complete. + +@subsection How do I link against .lib files? + +1. Build a C file with a function table. Put all functions you intend +to use in that table. This forces the linker to include all the object +files from the .lib. Maybe there is an option to force LINK.EXE to +include an object file. +2. Build a dummy 'LibMain'. +3. Build a .def with all the exports you need. +4. Link with your .lib using link.exe. + +or + +1. Extract all the object files from the .lib using LIB.EXE. +2. Build a dummy C file referencing all the functions you need, either +with a direct call or through an initialized function pointer. +3. Build a dummy LibMain. +4. Link all the objects with this file+LibMain. +5. Write a .def. +6. Link. + +You can use these methods to use MSVC (and many other runtime libs) +with Cygwin development tools. + +Note that this is a lot of work (half a day or so), but much less than +rewriting the runtime library in question from specs... + +(thanks to Jacob Navia (root@@jacob.remcomp.fr) for this explanation) + +@subsection How do I rebuild the tools on my NT box? + +Assuming that you have the src installed as /src, will build in +the directory /obj, and want to install the tools in /install: + +@example +bash +cd /obj +/src/configure --prefix=/install -v > configure.log 2>&1 +make > make.log 2>&1 +make install > install.log 2>&1 +@end example + +@subsection How can I compile a powerpc NT toolchain? + +Unfortunately, this will be difficult. It hasn't been built for +some time (late 1996) since Microsoft has dropped development of +powerpc NT. Exception handling/signals support semantics/args have been +changed for x86 and not updated for ppc so the ppc specific support would +have to be rewritten. We don't know of any other incompatibilities. +Please send us patches if you do this work! + +@subsection How can I compile an Alpha NT toolchain? + +We have not ported the tools to Alpha NT and do not have plans to +do so at the present time. We would be happy to add support +for Alpha NT if someone contributes the changes to us. + +@subsection How can I adjust the heap/stack size of an application? + +Pass heap/stack linker arguments to gcc. To create foo.exe with +a heap size of 1024 and a stack size of 4096, you would invoke +gcc as: + +@code{gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c} + +@subsection How can I find out which dlls are needed by an executable? + +objdump -p provides this information. + +@subsection How do I build a DLL? + +There's documentation that explains the process on the main Cygwin +project web page (http://sourceware.cygnus.com/cygwin/). + +@subsection How can I set a breakpoint at MainCRTStartup? + +Set a breakpoint at *0x401000 in gdb and then run the program in +question. + +@subsection How can I build a relocatable dll? + +You must execute the following sequence of five commands, in this +order: + +@example +$(LD) -s --base-file BASEFILE --dll -o DLLNAME OBJS LIBS -e ENTRY + +$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ + --base-file BASEFILE --output-exp EXPFILE + +$(LD) -s --base-file BASEFILE EXPFILE -dll -o DLLNAME OBJS LIBS -e ENTRY + +$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ + --base-file BASEFILE --output-exp EXPFILE + +$(LD) EXPFILE --dll -o DLLNAME OBJS LIBS -e ENTRY +@end example + +In this example, $(LD) is the linker, ld. + +$(DLLTOOL) is dlltool. + +$(AS) is the assembler, as. + +DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll. + +OBJS is the list of object files you want to put into the DLL. + +LIBS is the list of libraries you want to link the DLL against. For +example, you may or may not want -lcygwin. You may want -lkernel32. +Tcl links against -lcygwin -ladvapi32 -luser32 -lgdi32 -lcomdlg32 +-lkernel32. + +DEFFILE is the name of your definitions file. A simple DEFFILE would +consist of ``EXPORTS'' followed by a list of all symbols which should +be exported from the DLL. Each symbol should be on a line by itself. +Other programs will only be able to access the listed symbols. + +BASEFILE is a temporary file that is used during this five stage +process, e.g., tcl.base. + +EXPFILE is another temporary file, e.g., tcl.exp. + +ENTRY is the name of the function which you want to use as the entry +point. This function should be defined using the WINAPI attribute, +and should take three arguments: + int WINAPI startup (HINSTANCE, DWORD, LPVOID) + +This means that the actual symbol name will have an appended @@12, so if +your entry point really is named @samp{startup}, the string you should +use for ENTRY in the above examples would be @samp{startup@@12}. + +If your DLL calls any Cygwin API functions, the entry function will need +to initialize the Cygwin impure pointer. You can do that by declaring +a global variable @samp{_impure_ptr}, and then initializing it in the +entry function. Be careful not to export the global variable +@samp{_impure_ptr} from your DLL; that is, do not put it in DEFFILE. + +@example +/* This is a global variable. */ +struct _reent *_impure_ptr; +extern struct _reent *__imp_reent_data; + +int entry (HINSTANT hinst, DWORD reason, LPVOID reserved) +@{ + _impure_ptr = __imp_reent_data; + /* Whatever else you want to do. */ +@} +@end example + +You may put an optional `--subsystem windows' on the $(LD) lines. The +Tcl build does this, but I admit that I no longer remember whether +this is important. Note that if you specify a --subsytem <x> flag to ld, +the -e entry must come after the subsystem flag, since the subsystem flag +sets a different default entry point. + +You may put an optional `--image-base BASEADDR' on the $(LD) lines. +This will set the default image base. Programs using this DLL will +start up a bit faster if each DLL occupies a different portion of the +address space. Each DLL starts at the image base, and continues for +whatever size it occupies. + +Now that you've built your DLL, you may want to build a library so +that other programs can link against it. This is not required: you +could always use the DLL via LoadLibrary. However, if you want to be +able to link directly against the DLL, you need to create a library. +Do that like this: + +$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE + +$(DLLTOOL), $(AS), DLLNAME, and DEFFILE are the same as above. Make +sure you use the same DLLNAME and DEFFILE, or things won't work right. + +LIBFILE is the name of the library you want to create, e.g., +libtcl80.a. You can then link against that library using something +like -ltcl80 in your linker command. + +@subsection How can I debug what's going on? + +You can debug your application using @code{gdb}. Make sure you +compile it with the -g flag! If your application calls functions in +MS dlls, gdb will complain about not being able to load debug information +for them when you run your program. This is normal since these dlls +don't contain debugging information (and even if they did, that debug +info would not be compatible with gdb). + +@subsection Can I use a system trace mechanism instead? + +Yes. If you have a newer cygwin with the @code{strace.exe} program, +@code{strace} can run other cygwin programs with various debug and +trace messages enabled. For information on using the @code{strace} +program, see the Cygwin User's Guide or the file +@code{winsup/utils/utils/sgml}. + +If you have an older cygwin, you can set the <CODE>STRACE</CODE> +environment variable to <CODE>1</CODE>, and get a whole load of debug +information on your screen whenever a Cygwin app runs. This is an +especially useful tool to use when tracking bugs down inside the +Cygwin library. <CODE>STRACE</CODE> can be set to different values to +achieve different amounts of granularity. You can set it to +<CODE>0x10</CODE> for information about syscalls or <CODE>0x800</CODE> +for signal/process handling-related info, to name two. The strace +mechanism is well documented in the Cygwin library sources in the file +<CODE>winsup/include/sys/strace.h</CODE>. + +@subsection The linker complains that it can't find something. + +A common error is to put the library on the command line before +the thing that needs things from it. + +This is wrong @code{gcc -lstdc++ hello.cc}. +This is right @code{gcc hello.cc -lstdc++}. + +@subsection I use a function I know is in the API, but I still get a link +error. + +The function probably isn't declared in the header files, or +the UNICODE stuff for it isn't filled in. + +@subsection Can you make DLLs that are linked against libc ? + +Yes. + +@subsection Where is malloc.h? + +Include stdlib.h instead of malloc.h. + +@subsection Can I use my own malloc? + +If you define a function called @code{malloc} in your own code, and link +with the DLL, the DLL @emph{will} call your @code{malloc}. Needless to +say, you will run into serious problems if your malloc is buggy. + +If you run any programs from the DOS command prompt, rather than from in +bash, the DLL will try and expand the wildcards on the command line. +This process uses @code{malloc} @emph{before} your main line is started. +If you have written your own @code{malloc} to need some initialization +to occur after @code{main} is called, then this will surely break. + +@subsection Can I mix objects compiled with msvc++ and gcc? + +Yes, but only if you are combining C object files. MSVC C++ uses a +different mangling scheme than GNU C++, so you will have difficulties +combining C++ objects. + +@subsection Can I use the gdb debugger to debug programs built by VC++? + +No, not for full (high level source language) debugging. +The Microsoft compilers generate a different type of debugging +symbol information, which gdb does not understand. + +However, the low-level (assembly-type) symbols generated by +Microsoft compilers are coff, which gdb DOES understand. +Therefore you should at least be able to see all of your +global symbols; you just won't have any information about +data types, line numbers, local variables etc. + +@subsection Where can I find info on x86 assembly? + +CPU reference manuals for Intel's current chips are available in +downloadable PDF form on Intel's web site: + +@file{http://developer.intel.com/design/pro/manuals/} + +@subsection Shell scripts aren't running properly from my makefiles? + +You need to have . (dot) in your $PATH. You should NOT need to add +/bin/sh in front of each and every shell script invoked in your +Makefiles. + +@subsection What preprocessor do I need to know about? + +We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for +access to the Cygwin environment provided by the dll. + +We chose _WIN32 because this is what Microsoft defines in VC++ and +we thought it would be a good idea for compatibility with VC++ code +to follow their example. We use _MFC_VER to indicate code that should +be compiled with VC++. + +@subsection Where can I get f77 and objc components for B20 EGCS 1.1? + +B20-compatible versions of the f77 and objc components are available +from @file{http://www.xraylith.wisc.edu/~khan/software/gnu-win32/}. + +@subsection How should I port my Unix GUI to Windows? + +There are two basic strategies for porting Unix GUIs to Windows. + +The first is to use a portable graphics library such as tcl/tk, X11, or +V (and others?). Typically, you will end up with a GUI on Windows that +requires some runtime support. With tcl/tk, you'll want to include the +necessary library files and the tcl/tk DLLs. In the case of X11, you'll +need everyone using your program to have an X11 server installed. + +The second method is to rewrite your GUI using Win32 API calls (or MFC +with VC++). If your program is written in a fairly modular fashion, you +may still want to use Cygwin if your program contains a lot of shared +(non-GUI-related) code. That way you still gain some of the portability +advantages inherent in using Cygwin. + +@subsection Why not use DJGPP ? + +DJGPP is a similar idea, but for DOS instead of Win32. DJGPP uses a +"DOS extender" to provide a more reasonable operating interface for its +applications. The Cygwin toolset doesn't have to do this since all of +the applications are native WIN32. Applications compiled with the +Cygwin tools can access the Win32 API functions, so you can write +programs which use the Windows GUI. + +You can get more info on DJGPP by following +@file{http://www.delorie.com/}. diff --git a/winsup/doc/install.texinfo b/winsup/doc/install.texinfo new file mode 100644 index 000000000..29a80465e --- /dev/null +++ b/winsup/doc/install.texinfo @@ -0,0 +1,166 @@ +@chapter Installation Instructions +@section Contents + +The following packages are included in the full release: + +Development tools: +binutils, bison, byacc, dejagnu, diff, expect, flex, gas, gcc, gdb, +itcl, ld, libstdc++, make, patch, tcl, tix, tk + +User tools: +ash, bash, bzip2, diff, fileutils, findutils, gawk, grep, gzip, m4, +sed, shellutils, tar, textutils, time + +The user tools release only contains the user tools. + +Full source code is available for these tools. It is split into +these two units. + +@section Installing the binary release: + +Important! Be sure to remove any older versions of the Cygwin tools +from your PATH environment variable so you do not execute them by +mistake. + +To download the cygwin files, you may use whatever ftp, browser, or +other transfer program you are familiar with. To download multiple +files without interaction, you may wish to try the @code{wget} +program. Visit the cygwin home page's software listings to find a +pre-built copy of it. + +Connect to one of the ftp servers listed above and cd to the directory +containing the latest release. A list of mirror sites is at: + +@file{http://sourceware.cygnus.com/cygwin/mirrors.html}. + +If you want the development tools and the programs necessary to run +the GNU configure mechanism, you should download the full binary release +called @file{full.exe}. If you only care about the user tools +listed above, download @file{usertools.exe} instead. + +If you have an unreliable connection, download the appropriate binary in +smaller chunks instead. For the split cdk installer, get the files in +the @file{full-split} subdirectory. Once downloaded, combine the +split files at the command prompt by doing a: + +@smallexample +copy /b xaa + xab + xac + ... + xak + xal full.exe +del xa*.* +@end smallexample + +A similar process can be used for the user tools. + +Once you have an install executable on your system, run it. If +a previous version of the software is detected, it will offer to +uninstall it for you. + +Next it will ask you to choose an install location. The default is +@file{<system-drive>:\cygnus\cygwin-b20}. Feel free to choose another +location if you would prefer. + +Finally, it will ask you for the name of the Program Files folder +shortcut to add. By default, the installer will create +a @file{Cygwin B20} entry in a +folder called @file{Cygnus Solutions}. When this step is completed, it +will install the tools and exit. + +At this point, you should be able to look under the start menu and +select "Cygwin B20". This will pop up a bash shell with all special +environment variables set up for you. If you are running Windows 95 or +98 and are faced with the error message "Out of environment space", you +need to increase the amount of environment space in your config.sys and +try again. Adding the line @code{shell=C:\command.com /e:4096 /p} +should do the trick if @code{C:} is your system drive letter. + +There are two remaining thing you should do from this prompt. +First, you need to type @code{mkdir -p /tmp} to ensure that a directory +for temporary files exists for programs that expect to find one there. + +Second, if you are installing the full distribution +(@file{full.exe}), various programs will need to be able to find +@file{/bin/sh}. You should @file{mkdir -p /bin} and put a copy of +@file{sh.exe} there, removing the older version, if present. You can +use the @file{mount} utility to select which drive letter is mounted as +@file{/}. See the Frequently Asked Questions (FAQ) file for more +information on @file{mount}. + +If you should ever want to uninstall the tools, you may do so +via the "Add/Remove Programs" control panel. + +@section Installing the source code + +Before downloading the source code corresponding to the release, +you should install the latest release of the tools (either the full +release or just the user tools). + +Create the directory that will house the source code. @file{cd} +there. + +Connect to one of the ftp servers listed above and cd to the directory +containing the latest release. A list of mirror sites is at: + +@file{http://sourceware.cygnus.com/cygwin/mirrors.html}. + +If you want the user tools source code, @file{cd} into the +@file{user-src-split} subdirectory. Download the files there. If you +want the development tools sources, @file{cd} into the +@file{dev-src-split} subdirectory. Download the files there. + +Back in the Windows command shell, for the user tools source: + +@smallexample +copy /b xba + xbb + xbc + xbd + xbe + xbf + xbg user-src.tar.bz2 +del xb*.* +bunzip2 user-src.tar.bz2 +tar xvf user-src.tar +@end smallexample + +For the development tools source: + +@smallexample +copy /b xca + xcb + xcc + xcd + ... + xck + xcl dev-src.tar.bz2 +del xc*.* +bunzip2 dev-src.tar.bz2 +tar xvf dev-src.tar +@end smallexample + +Both expand into a directory called @file{src}. + +Note: if you want the sources corresponding to everything in the +full.exe binary installer, you will need to download and expand both +the user-src.tar.bz2 and dev-src.tar.bz2 source archives! + +And you should be done... + +@section Upgrading to B20.1 + +If you downloaded the original B20.0 release, you should definitely at +least upgrade the Cygwin library to the version present in B20.1. To do +this, download the file +@file{cygwin-b20/cygwin1-20.1.dll.bz2} from one of our mirror sites, +decompress it with bunzip2, and then install the dll, replacing +the file cygwin-b20/H-i586-cygwin32/bin/cygwin1.dll in your original +installation of 20.0. + +There are some additional patches in a few of the other tools +(including a gcc change that makes -mno-cygwin find the correct header +files). In addition, the tools have been built with a compiled-in path +of /cygnus/cygwin-b20/ which will make some tools such as bison find +their library files without help from environment variables. +To install the full 20.1 release, you will need to download the +correct installer from scratch. It will offer to uninstall the existing +release and replace it with 20.1 (You should choose to uninstall b20 and +proceed). + +We have diff files on the ftp site that can be used to upgrade the +original B20.0 sources. 20.0-20.1-dev-src.diff.bz2 upgrades the +development tools sources. 20.0-20.1-user-src.diff.bz2 upgrades the +user tools sources. They come compressed so you'll need to bunzip2 them +before proceeding. As an example, if the development tools are in the +directory called "src" and the patch is in the directory above it, apply +the patch as follows: + +@smallexample +cd src +patch -p1 -E < ../20.0-20.1-dev-src.diff +@end smallexample diff --git a/winsup/doc/legal.sgml b/winsup/doc/legal.sgml new file mode 100644 index 000000000..721899c46 --- /dev/null +++ b/winsup/doc/legal.sgml @@ -0,0 +1,32 @@ +<LegalNotice id="legal"> + +<Para>Copyright © 1998,1999 Cygnus Solutions.</Para> + +<!-- + +<Para>GNUPro™, the GNUPro™ logo, and the Cygnus Solutions +logo are trademarks of Cygnus Solutions. All other brand and product +names are trademarks of their respective owners.</Para> + +<Para>Permission is granted to make and distribute verbatim copies of +this documentation provided the copyright notice and this permission +notice are preserved on all copies.</Para> + +<Para>Permission is granted to copy and distribute modified versions +of this documentation under the conditions for verbatim copying, +provided that the entire resulting derived work is distributed under +the terms of a permission notice identical to this one.</Para> + +<Para>Permission is granted to copy and distribute translations of +this documentation into another language, under the above conditions +for modified versions, except that this permission notice may be +stated in a translation approved by the Free Software +Foundation.</Para> + +<Para>This documentation has been prepared by Cygnus Solutions +Technical Publications; to contact the Cygnus Solutions Technical +Publications staff, email: <Email>doc@cygnus.com</Email>.</Para> + +--> + +</LegalNotice> diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.sgml new file mode 100644 index 000000000..5f95dd288 --- /dev/null +++ b/winsup/doc/ntsec.sgml @@ -0,0 +1,316 @@ + +<sect1 id="ntsec"><title>NTSEC Documentation</title> + +<para>The design goal of the ntsec patch was to get a more UNIX like +permission structure based upon the security features of Windows NT. +To describe the changes, I will give a short overview of NT security +in chapter one.</para> +<para>Chapter two discusses the changes in ntsec related to privileges on +processes.</para> +<para>Chapter three shows the UNIX like setting of file permissions.</para> + +<para>The setting of UNIX like object permissions is controlled by the new +<EnVar>CYGWIN</EnVar> variable setting <literal>(no)ntsec</literal>.</para> + +<para>On NT ntsec is now turned on by default.</para> + +<sect2 id="ntsec-common"><title>NT security</title> + +<para>The NT security allows a process to allow or deny access of +different kind to `objects'. `Objects' are files, processes, +threads, semaphores, etc.</para> + +<para>The main data structure of NT security is the `security descriptor' +(SD) structure. It explains the permissions, that are granted (or denied) +to an object and contains information, that is related to so called +`security identifiers' (SID).</para> + +<para>An SID is a unique identifier for users, groups and domains. +SIDs are comparable to UNIX UIDs and GIDs, but are more complicated +because they are unique across networks. Example:</para> + +<example> +<screen> +SID of a system `foo': + + S-1-5-21-165875785-1005667432-441284377 + +SID of a user `johndoe' of the system `foo': + + S-1-5-21-165875785-1005667432-441284377-1023 +</screen> +</example> + +<para>The above example shows the convention for printing SIDs. The leading +`S' should show that it is a SID. The next number is a version number which +is always 1. The next number is the so called `top-level authority' that +identifies the source that issued the SID.</para> + +<para>While each system in a NT network has it's own SID, the situation +is modified in NT domains: The SID of the domain controller is the +base SID for each domain user. If an NT user has one account as domain +user and another account on his local machine, this accounts are under +any circumstances DIFFERENT, regardless of the usage of the same user +name and password!</para> + +<example> +<screen> +SID of a domain `bar': + + S-1-5-21-186985262-1144665072-740312968 + +SID of a user `johndoe' in the domain `bar': + + S-1-5-21-186985262-1144665072-740312968-1207 +</screen> +</example> + +<para>The last part of the SID, the so called `relative identifier' (RID), +is used as UID and/or GID under cygwin. As the name and the above example +implies, this id is unique only relative to one system or domain.</para> + +<para>Note, that it's possible, that an user has the same RID on two +different systems. The resulting SIDs are nevertheless different, so +the SIDs are representing different users in an NT network.</para> + +<para>There is a big difference between UNIX IDs and NT SIDs, the existence of +the so called `well known groups'. For example UNIX has no GID for the +group of `all users'. NT has an SID for them, called `Everyone' in the +English versions. The SIDs of well-known groups are not unique across +an NT network but their meanings are unmistakable. +Examples of well-known groups:</para> + +<screen> +<example> +everyone S-1-1-0 +creator/owner S-1-3-0 +batch process (via `at') S-1-5-3 +authenticated users S-1-5-11 +system S-1-5-18 +</screen> +</example> + +<para>The last important group of SIDs are the `predefined groups'. This +groups are used mainly on systems outside of domains to simplify the +administration of user permissions. The corresponding SIDs are not unique +across the network so they are interpreted only locally:</para> + +<screen> +<example> +administrators S-1-5-32-544 +users S-1-5-32-545 +guests S-1-5-32-546 +... +</screen> +</example> + +<para>Now, how are permissions given to objects? A process may assign an SD +to the object. The SD of an object consists of three parts:</para> + +<itemizedlist spacing="compact"> +<listitem><para>- the SID of the owner </para></listitem> +<listitem><para>- the SID of the group </para></listitem> +<listitem><para>- a list of SIDs with their permissions, called +`access control list' (ACL) </para></listitem> +</itemizedlist> + +<para>UNIX is able to create three different permissions, the permissions +for the owner, for the group and for the world. In contrast the ACL +has a potentially infinite number of members. Every member is a so called +`access control element' (ACE). An ACE contains three parts:</para> + +<itemizedlist spacing="compact"> +<listitem><para>- the type of the ACE </para></listitem> +<listitem><para>- permissions, described with a DWORD </para></listitem> +<listitem><para>- the SID, for which the above mentioned permissions are +set </para></listitem> +</itemizedlist> + +<para>The two important types of ACEs are the `access allowed ACE' and the +`access denied ACE'. The ntsec patch only uses `access allowed ACEs'.</para> + +<para>The possible permissions on objects are more complicated than in +UNIX. For example, the permission to delete an object is different +from the write permission.</para> + +<para>With the aforementioned method NT is able to grant or revoke permissions +to objects in a far more specific way. But what about cygwin? In a POSIX +environment it would be fine to have the security behavior of a POSIX +system. The NT security model is able to reproduce the POSIX model. +The ntsec patch tries to do this in cygwin.</para> + +<para>The creation of explicit object security is a bit complicated, so +typically only two simple variations are used:</para> + +<itemizedlist spacing="compact"> +<listitem><para>- default permissions, computed by the operating system </para></listitem> +<listitem><para>- each permission to everyone </para></listitem> +</itemizedlist> + +<para>For parameters to functions that create or open securable objects another +data structure is used, the `security attributes' (SA). This structure +contains an SD and a flag, that specifies whether the returned handle +to the created or opened object is inherited to child processes or not. +This property is not important for the ntsec patch description, so in +this document SDs and SAs are more or less identical.</para> + +</sect2> + +<sect2 id="ntsec-processes"><title>Process privileges</title> + +<para>Any process started under control of cygwin has a semaphore attached +to it, that is used for signaling purposes. The creation of this semaphore +can be found in sigproc.cc, function `getsem'. The first parameter to the +function call `CreateSemaphore' is an SA. Without ntsec patch this SA +assigns default security to the semaphore. There is a simple disadvantage: +Only the owner of the process may send signals to it. Or, in other words, +if the owner of the process is not a member of the administrators' group, +no administrator may kill the process! This is especially annoying, if +processes are started via service manager.</para> + +<para>The ntsec patch now assigns an SA to the process control semaphore, that +has each permission set for the user of the process, for the +administrators' group and for `system', which is a synonym for the +operating system itself. The creation of this SA is done by the function +`sec_user', that can be found in `shared.cc'. Each member of the +administrators' group is now allowed to send signals to any process +created in cygwin, regardless of the process owner.</para> + +<para>Moreover, each process now has the appropriate security settings, when +it is started via `CreateProcess'. You will find this in function +`spawn_guts' in module `spawn.cc'. The security settings for starting a +process in another user context have to add the sid of the new user, too. +In the case of the `CreateProcessAsUser' call, sec_user creates an SA with +an additional entry for the sid of the new user.</para> + +</sect2> + +<sect2 id="ntsec-files"><title>File permissions</title> + +<para>If ntsec is turned on, file permissions are set as in UNIX. An SD is +assigned to the file containing the owner and group and ACEs for the +owner, the group and `Everyone'. If the group of the file is not the +administrators' group, the administrators' group gets the permissions +to read the permissions (yes, this is an own permission flag +<literal>:-)</literal>) and to take the ownership on this file. +If the file's group is the administrators group itself, this behaviour +is modified to support the typical behaviour of NT better: +As you know, if one is member of admin group, all her files are owned +by the group instead of by her. This is not the case with ntsec but the +other admins should have easier access to the administrative files. +So in this case the admin group gets additionally the permissions to +write permissions and to write extended attributes, also in the case +where group permissions are set to 0.</para> + +<para>The complete settings of UNIX like permissions can be found in the file +`security.cc'. The two functions `get_nt_attribute' and `set_nt_attribute' +are the main code. The reading and writing of the SDs is done by the +functions `ReadSD' and `WriteSD'. They are using the Backup API functions +`BackupRead' and `BackupWrite', that have the advantage not to crash, +if they are used on non NTFS file systems! These crashes are the default +behavior of the security API, if it's used on, e.g., FAT or SAMBA +file systems <literal>:-(</literal></para> + +<para>Unfortunately, the settings of NT file security are only available +on NTFS. SAMBA doesn't support them.</para> + +<para>If you are creating a file `foo' outside of cygwin, you will see something +like the following on <command>ls -ln</command>:</para> + +<para>If your login is member of the administrators' group:</para> +<screen> + rwxrwxrwx 1 544 513 ... foo +</screen> +<para>if not:</para> +<screen> + rwxrwxrwx 1 1000 513 ... foo +</screen> + +<para>Note the user and group IDs. 544 is the UID of the administrators' group. +This is a `feature' <literal>:-P</literal> of WinNT. If one is a member of +the administrators' group, every file, that he has created is owned by the +administrators' group, instead by him.</para> + +<para>The second example shows the UID of the first user, that has been +created with NT's the user administration tool. The users and groups are +sequentially numbered, starting with 1000. Users and groups are using the +same numbering scheme, so a user and a group don't share the same ID.</para> + +<para>In both examples the GID 513 is of special interest. This GID is a +well known group with different naming in local systems and domains. +Outside of domains the group is named 'None' (`Kein' in German, `Aucun' +in French, etc.), in domains it is named 'Domain Users'. Unfortunately, +the group `None' is never shown in the user admin tool outside of domains! +This is very confusing but it seems that this has no negativ influences.</para> + +<para>To work correctly the ntsec patch depends on reasoned files +<filename>/etc/passwd/</filename> and <filename>/etc/group</filename>. +The names and the IDs must correspond to the appropriate +NT IDs! The IDs used in cygwin are the RID of the NT SID, as aforementioned. +An SID of e.g. the user `corinna' on my NT workstation:</para> + +<example> +<screen> + S-1-5-21-165875785-1005667432-441284377-1000 +</screen> +</example> + +<para>Note the last number: It's the RID 1000, the cygwin's UID.</para> + +<para>Unfortunately, workstations and servers outside of domains are not +able to set primary groups! In these cases, where there is no correlation +of users to primary groups, NT returns 513 (None) as primary group, +regardless of the membership to regular groups of these users.</para> + +<para>when using <command>mkpasswd -l -g</command> on such systems, you +have to change the primary group by hand if `None' as primary group is +not what you want (and I'm sure, it's not what you want!)</para> + +<para>To get help in creating correct passwd and group files, look at +the following examples, that are part of my files. With the exception +of my personal user entry, all entries are well known entries. For a +better understanding, the names are translated to the equivalents of the +English NT version:</para> + +<example> +<title>/etc/passwd:</title> +<screen> +everyone:*:0:0::: +system:*:18:18::: +administrator::500:544::/home/root:/bin/bash +guest:*:501:546::: +administrators:*:544:544::/home/root: +corinna::1000:547:Corinna Vinschen:/home/corinna:/bin/tcsh +</screen> +</example> + +<example> +<title>/etc/group:</title> +<screen> +everyone::0: +system::18: +none::513: +administrators::544: +users::545: +guests::546: +powerusers::547: +</screen> +</example> + +<para>Groups may be mentioned in the passwd file, too. This has two +advantages:</para> +<itemizedlist spacing="compact"> +<listitem><para>- Because NT assigns them to files as owners, a +<command>ls -l</command> is often better readable. </para></listitem> +<listitem><para>- Moreover it's possible to assigned them to files as +owners with cygwin's <command>chown</command>. </para></listitem> +</itemizedlist> + +<para>The group `system' is the aforementioned synonym for the operating system +itself and is normally the owner of processes, that are started through +service manager. The same is true for files, that are created by +processes, which are started through service manager.</para> + +</sect2> + +</sect1> diff --git a/winsup/doc/overview.sgml b/winsup/doc/overview.sgml new file mode 100644 index 000000000..ea476dd49 --- /dev/null +++ b/winsup/doc/overview.sgml @@ -0,0 +1,87 @@ +<chapter id="overview"><title>Cygwin Overview</title> + +<sect1><title>What is it?</title> + +<para>The Cygwin tools are ports of the popular GNU development +tools and utilities for Windows NT and 9x. They function through the +use of the Cygwin library which provides the UNIX system calls and +environment that these programs require.</para> + +<para>With the tools installed, programmers may write Win32 +console or GUI applications that make use of the standard Microsoft +Win32 API and/or the Cygwin API. As a result, it is possible to +easily port many significant UNIX programs without the need for +extensive changes to the source code. This includes configuring and +building most of the available GNU software (including the development +tools included with the Cygwin distributions). Even if the +compiler tools are of little to no use to you, you may have +interest in the many standard UNIX utilities. They can be used both +from the bash shell (provided) or from the command.com.</para> + +</sect1> + +<sect1><title>Are the Cygwin tools free software?</title> + +<para>Yes. Parts are GNU software (gcc, gas, ld, etc...), parts are +covered by the standard X11 license, some of it is public domain, +some of it was written by Cygnus and placed under the GPL. None of it +is shareware. You don't have to pay anyone to use it but you should be +sure to read the copyright section of the FAQ more more information on +how the GNU General Public License may affect your use of these +tools. If you intend to port a proprietary application using the Cygwin +library, you may want the Cygwin proprietary-use license. +For more information about the +proprietary-use license, please contact sales@cygnus.com. Customers of +the native Win32 GNUPro should feel free to submit bug reports and ask +questions through the normal channels. All other questions should be +sent to the project mailing list cygwin@sourceware.cygnus.com.</para> + +</sect1> + +<sect1><title>A brief history of the Cygwin project</title> + +<para>The first thing done was to enhance the development tools (gcc, +gdb, gas, et al) so that they could generate/interpret Win32 native +object files.</para> + +<para>The next task was to port the tools to Win NT/9x. We could have +done this by rewriting large portions of the source to work within the +context of the Win32 API. But this would have meant spending a huge +amount of time on each and every tool. Instead, we took a +substantially different approach by writing a shared library +(the Cygwin DLL) that adds the necessary UNIX-like functionality +missing from the Win32 API (fork, spawn, signals, select, sockets, +etc.). We call this new interface the Cygwin API. Once written, it +was possible to build working Win32 tools using UNIX-hosted +cross-compilers, linking against this library.</para> + +<para>From this point, we pursued the goal of producing native tools +capable of rebuilding themselves under Windows 9x and NT (this is +often called self-hosting). Since neither OS ships with standard UNIX +user tools (fileutils, textutils, bash, etc...), we had to get the GNU +equivalents working with the Cygwin API. Most of these tools were +previously only built natively so we had to modify their configure +scripts to be compatible with cross-compilation. Other than the +configuration changes, very few source-level changes had to be +made. Running bash with the development tools and user tools in place, +Windows 9x and NT look like a flavor of UNIX from the perspective of +the GNU configure mechanism. Self hosting was achieved as of the beta +17.1 release.</para> + +</sect1> + +DOCTOOL-INSERT-ov-ex-unix +DOCTOOL-INSERT-ov-ex-win +<sect1><title>Highlights of Cygwin Functionality</title> +DOCTOOL-INSERT-ov-hi-intro +DOCTOOL-INSERT-ov-hi-win9xnt +DOCTOOL-INSERT-ov-hi-perm +DOCTOOL-INSERT-ov-hi-files +DOCTOOL-INSERT-ov-hi-textvsbinary +DOCTOOL-INSERT-ov-hi-ansiclib +DOCTOOL-INSERT-ov-hi-process +DOCTOOL-INSERT-ov-hi-signals +DOCTOOL-INSERT-ov-hi-sockets +DOCTOOL-INSERT-ov-hi-select +</sect1> +</chapter> diff --git a/winsup/doc/overview2.sgml b/winsup/doc/overview2.sgml new file mode 100644 index 000000000..9fad7cebe --- /dev/null +++ b/winsup/doc/overview2.sgml @@ -0,0 +1,307 @@ +<sect1 id="ov-ex-unix"><title>Expectations for UNIX Programmers</title> + +<para>Developers coming from a UNIX background will find a set of utilities +they are already comfortable using, including a working UNIX shell. The +compiler tools are the standard GNU compilers most people will have previously +used under UNIX, only ported to the Windows host. Programmers wishing to port +UNIX software to Windows NT or 9x will find that the Cygwin library provides +an easy way to port many UNIX packages, with only minimal source code +changes.</para> +</sect1> + +<sect1 id="ov-ex-win"><title>Expectations for Windows Programmers</title> +<para>Developers coming from a Windows background will find a set of tools capable +of writing console or GUI executables that rely on the Microsoft Win32 API. +The linker and dlltool utility may be used to write Windows Dynamically Linked +Libraries (DLLs). The resource compiler "windres" is also provided with the +native Windows GNUPro tools. All tools may be used from the Microsoft command +line prompt, with full support for normal Windows pathnames.</para> +</sect1> + +<sect2 id="ov-hi-intro"><title>Introduction</title> <para>When a binary linked +against the library is executed, the Cygwin DLL is loaded into the +application's text segment. Because we are trying to emulate a UNIX kernel +which needs access to all processes running under it, the first Cygwin DLL to +run creates shared memory areas that other processes using separate instances +of the DLL can access. This is used to keep track of open file descriptors and +assist fork and exec, among other purposes. In addition to the shared memory +regions, every process also has a per_process structure that contains +information such as process id, user id, signal masks, and other similar +process-specific information.</para> + +<para>The DLL is implemented using the Win32 API, which allows it to run on all +Win32 hosts. Because processes run under the standard Win32 subsystem, they +can access both the UNIX compatibility calls provided by Cygwin as well as +any of the Win32 API calls. This gives the programmer complete flexibility in +designing the structure of their program in terms of the APIs used. For +example, they could write a Win32-specific GUI using Win32 API calls on top of +a UNIX back-end that uses Cygwin.</para> + +<para>Early on in the development process, we made the important design +decision that it would not be necessary to strictly adhere to existing UNIX +standards like POSIX.1 if it was not possible or if it would significantly +diminish the usability of the tools on the Win32 platform. In many cases, an +environment variable can be set to override the default behavior and force +standards compliance.</para> +</sect2> + +<sect2 id="ov-hi-win9xnt"><title>Supporting both Windows NT and 9x</title> +<para>While Windows 95 and Windows 98 are similar enough to each other that we +can safely ignore the distinction when implementing Cygwin, Windows NT is an +extremely different operating system. For this reason, whenever the DLL is +loaded, the library checks which operating system is active so that it can act +accordingly.</para> + +<para>In some cases, the Win32 API is only different for +historical reasons. In this situation, the same basic functionality is +available under Windows 9x and NT but the method used to gain this +functionality differs. A trivial example: in our implementation of +uname, the library examines the sysinfo.dwProcessorType structure +member to figure out the processor type under Windows 9x. This field +is not supported in NT, which has its own operating system-specific +structure member called sysinfo.wProcessorLevel.</para> + +<para>Other differences between NT and 9x are much more fundamental in +nature. The best example is that only NT provides a security model.</para> +</sect2> + +<sect2 id="ov-hi-perm"><title>Permissions and Security</title> +<para>Windows NT includes a sophisticated security model based on Access +Control Lists (ACLs). Although some modern UNIX operating systems include +support for ACLs, Cygwin maps Win32 file ownership and permissions to the +more standard, older UNIX model. The chmod call maps UNIX-style permissions +back to the Win32 equivalents. Because many programs expect to be able to find +the /etc/passwd and /etc/group files, we provide utilities that can be used to +construct them from the user and group information provided by the operating +system.</para> + +<para>Under Windows NT, the administrator is permitted to chown files. There +is currently no mechanism to support the setuid concept or API call. Although +we hope to support this functionality at some point in the future, in practice, +the programs we have ported have not needed it.</para> + +<para>Under Windows 9x, the situation is considerably different. Since a +security model is not provided, Cygwin fakes file ownership by making all +files look like they are owned by a default user and group id. As under NT, +file permissions can still be determined by examining their read/write/execute +status. Rather than return an unimplemented error, under Windows 9x, the +chown call succeeds immediately without actually performing any action +whatsoever. This is appropriate since essentially all users jointly own the +files when no concept of file ownership exists.</para> + +<para>It is important that we discuss the implications of our "kernel" using +shared memory areas to store information about Cygwin processes. Because +these areas are not yet protected in any way, in principle a malicious user +could modify them to cause unexpected behavior in Cygwin processes. While +this is not a new problem under Windows 9x (because of the lack of operating +system security), it does constitute a security hole under Windows NT. +This is because one user could affect the Cygwin programs run by +another user by changing the shared memory information in ways that +they could not in a more typical WinNT program. For this reason, it +is not appropriate to use Cygwin in high-security applications. In +practice, this will not be a major problem for most uses of the +library.</para> +</sect2> + +<sect2 id="ov-hi-files"><title>File Access</title> <para>Cygwin supports +both Win32- and POSIX-style paths, using either forward or back slashes as the +directory delimiter. Paths coming into the DLL are translated from Win32 to +POSIX as needed. As a result, the library believes that the file system is a +POSIX-compliant one, translating paths back to Win32 paths whenever it calls a +Win32 API function. UNC pathnames (starting with two slashes) are +supported.</para> + +<para>The layout of this POSIX view of the Windows file system space is stored +in the Windows registry. While the slash ('/') directory points to the system +partition by default, this is easy to change with the Cygwin mount utility. +In addition to selecting the slash partition, it allows mounting arbitrary +Win32 paths into the POSIX file system space. Many people use the utility to +mount each drive letter under the slash partition (e.g. C:\ to /c, D:\ to /d, +etc...).</para> + +<para>The library exports several Cygwin-specific functions that can be used +by external programs to convert a path or path list from Win32 to POSIX or vice +versa. Shell scripts and Makefiles cannot call these functions directly. +Instead, they can do the same path translations by executing the cygpath +utility program that we provide with Cygwin.</para> + +<para>Win32 file systems are case preserving but case insensitive. Cygwin +does not currently support case distinction because, in practice, few UNIX +programs actually rely on it. While we could mangle file names to support case +distinction, this would add unnecessary overhead to the library and make it +more difficult for non-Cygwin applications to access those files.</para> + +<para>Symbolic links are emulated by files containing a magic cookie followed +by the path to which the link points. They are marked with the System +attribute so that only files with that attribute have to be read to determine +whether or not the file is a symbolic link. Hard links are fully supported +under Windows NT on NTFS file systems. On a FAT file system, the call falls +back to simply copying the file, a strategy that works in many cases.</para> + +<para>The inode number for a file is calculated by hashing its full Win32 path. +The inode number generated by the stat call always matches the one returned in +d_ino of the dirent structure. It is worth noting that the number produced by +this method is not guaranteed to be unique. However, we have not found this to +be a significant problem because of the low probability of generating a +duplicate inode number.</para> +</sect2> + +<sect2 id="ov-hi-textvsbinary"><title>Text Mode vs. Binary Mode</title> +<para>Interoperability with other Win32 programs such as text editors was +critical to the success of the port of the development tools. Most Cygnus +customers upgrading from the older DOS-hosted toolchains expected the new +Win32-hosted ones to continue to work with their old development +sources.</para> + +<para>Unfortunately, UNIX and Win32 use different end-of-line terminators in +text files. Consequently, carriage-return newlines have to be translated on +the fly by Cygwin into a single newline when reading in text mode. The +control-z character is interpreted as a valid end-of-file character for a +similar reason.</para> + +<para>This solution addresses the compatibility requirement at the expense of +violating the POSIX standard that states that text and binary mode will be +identical. Consequently, processes that attempt to lseek through text files can +no longer rely on the number of bytes read as an accurate indicator of position +in the file. For this reason, the CYGWIN environment variable can be +set to override this behavior.</para> +</sect2> + +<sect2 id="ov-hi-ansiclib"><title>ANSI C Library</title> +<para>We chose to include +Cygnus' own existing ANSI C library +"newlib" as part of the library, rather than write all of the lib C +and math calls from scratch. Newlib is a BSD-derived ANSI C library, +previously only used by cross-compilers for embedded systems +development.</para> + +<para>The reuse of existing free implementations of such things +as the glob, regexp, and getopt libraries saved us considerable +effort. In addition, Cygwin uses Doug Lea's free malloc +implementation that successfully balances speed and compactness. The +library accesses the malloc calls via an exported function pointer. +This makes it possible for a Cygwin process to provide its own +malloc if it so desires.</para> +</sect2> + +<sect2 id="ov-hi-process"><title>Process Creation</title> +<para>The fork call in Cygwin is particularly interesting because it +does not map well on top of the Win32 API. This makes it very +difficult to implement correctly. Currently, the Cygwin fork is a +non-copy-on-write implementation similar to what was present in early +flavors of UNIX.</para> + +<para>The first thing that happens when a parent process +forks a child process is that the parent initializes a space in the +Cygwin process table for the child. It then creates a suspended +child process using the Win32 CreateProcess call. Next, the parent +process calls setjmp to save its own context and sets a pointer to +this in a Cygwin shared memory area (shared among all Cygwin +tasks). It then fills in the child's .data and .bss sections by +copying from its own address space into the suspended child's address +space. After the child's address space is initialized, the child is +run while the parent waits on a mutex. The child discovers it has +been forked and longjumps using the saved jump buffer. The child then +sets the mutex the parent is waiting on and blocks on another mutex. +This is the signal for the parent to copy its stack and heap into the +child, after which it releases the mutex the child is waiting on and +returns from the fork call. Finally, the child wakes from blocking on +the last mutex, recreates any memory-mapped areas passed to it via the +shared area, and returns from fork itself.</para> + +<para>While we have some +ideas as to how to speed up our fork implementation by reducing the +number of context switches between the parent and child process, fork +will almost certainly always be inefficient under Win32. Fortunately, +in most circumstances the spawn family of calls provided by Cygwin +can be substituted for a fork/exec pair with only a little effort. +These calls map cleanly on top of the Win32 API. As a result, they +are much more efficient. Changing the compiler's driver program to +call spawn instead of fork was a trivial change and increased +compilation speeds by twenty to thirty percent in our +tests.</para> + +<para>However, spawn and exec present their own set of +difficulties. Because there is no way to do an actual exec under +Win32, Cygwin has to invent its own Process IDs (PIDs). As a +result, when a process performs multiple exec calls, there will be +multiple Windows PIDs associated with a single Cygwin PID. In some +cases, stubs of each of these Win32 processes may linger, waiting for +their exec'd Cygwin process to exit.</para> +</sect2> + +<sect2 id="ov-hi-signals"><title>Signals</title> +<para>When +a Cygwin process starts, the library starts a secondary thread for +use in signal handling. This thread waits for Windows events used to +pass signals to the process. When a process notices it has a signal, +it scans its signal bitmask and handles the signal in the appropriate +fashion.</para> + +<para>Several complications in the implementation arise from the +fact that the signal handler operates in the same address space as the +executing program. The immediate consequence is that Cygwin system +functions are interruptible unless special care is taken to avoid +this. We go to some lengths to prevent the sig_send function that +sends signals from being interrupted. In the case of a process +sending a signal to another process, we place a mutex around sig_send +such that sig_send will not be interrupted until it has completely +finished sending the signal.</para> + +<para>In the case of a process sending +itself a signal, we use a separate semaphore/event pair instead of the +mutex. sig_send starts by resetting the event and incrementing the +semaphore that flags the signal handler to process the signal. After +the signal is processed, the signal handler signals the event that it +is done. This process keeps intraprocess signals synchronous, as +required by POSIX.</para> + +<para>Most standard UNIX signals are provided. Job +control works as expected in shells that support +it.</para> +</sect2> + +<sect2 id="ov-hi-sockets"><title>Sockets</title> +<para>Socket-related calls in Cygwin simply +call the functions by the same name in Winsock, Microsoft's +implementation of Berkeley sockets. Only a few changes were needed to +match the expected UNIX semantics - one of the most troublesome +differences was that Winsock must be initialized before the first +socket function is called. As a result, Cygwin has to perform this +initialization when appropriate. In order to support sockets across +fork calls, child processes initialize Winsock if any inherited file +descriptor is a socket.</para> + +<para>Unfortunately, implicitly loading DLLs +at process startup is usually a slow affair. Because many processes +do not use sockets, Cygwin explicitly loads the Winsock DLL the +first time it calls the Winsock initialization routine. This single +change sped up GNU configure times by thirty +percent.</para> +</sect2> + +<sect2 id="ov-hi-select"><title>Select</title> +<para>The UNIX select function is another +call that does not map cleanly on top of the Win32 API. Much to our +dismay, we discovered that the Win32 select in Winsock only worked on +socket handles. Our implementation allows select to function normally +when given different types of file descriptors (sockets, pipes, +handles, and a custom /dev/windows Windows messages +pseudo-device).</para> + +<para>Upon entry into the select function, the first +operation is to sort the file descriptors into the different types. +There are then two cases to consider. The simple case is when at +least one file descriptor is a type that is always known to be ready +(such as a disk file). In that case, select returns immediately as +soon as it has polled each of the other types to see if they are +ready. The more complex case involves waiting for socket or pipe file +descriptors to be ready. This is accomplished by the main thread +suspending itself, after starting one thread for each type of file +descriptor present. Each thread polls the file descriptors of its +respective type with the appropriate Win32 API call. As soon as a +thread identifies a ready descriptor, that thread signals the main +thread to wake up. This case is now the same as the first one since +we know at least one descriptor is ready. So select returns, after +polling all of the file descriptors one last time.</para> +</sect2> diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml new file mode 100644 index 000000000..2338b18ff --- /dev/null +++ b/winsup/doc/pathnames.sgml @@ -0,0 +1,272 @@ +<sect1 id="using-pathnames"><title>Mapping path names</title> + +<sect2><title>Introduction</title> + +<para>Cygwin supports both Win32- and POSIX-style paths, where +directory delimiters may be either forward or back slashes. UNC +pathnames (starting with two slashes and a network name) are also +supported.</para> + +<para>POSIX operating systems (such as Linux) do not have the concept +of drive letters. Instead, all absolute paths begin with a +slash (instead of a drive letter such as "c:") and all file systems +appear as subdirectories (for example, you might buy a new disk and +make it be the <filename>/disk2</filename> directory).</para> + +<para>Because many programs written to run on UNIX systems assume +the existance of a single unified POSIX file system structure, Cygwin +maintains a special internal POSIX view of the Win32 file system +that allows these programs to successfully run under Windows. Cygwin +uses this mapping to translate between Win32 and POSIX paths as +necessary.</para> + +</sect2> + +<sect2 id="mount-table"><title>The Cygwin Mount Table</title> + +<para>The <command>mount</command> utility program is used to +to map Win32 drives and network shares into Cygwin's internal POSIX +directory tree. This is a similar concept to the typical UNIX mount +program. For those people coming from a Windows background, the +<command>mount</command> utility is very similar to the old DOS +<command>join</command>, in that it makes your drive letters appear as +subdirectories somewhere else.</para> + +<para>The mapping is stored in the current user's Cygwin +<FirstTerm>mount table</FirstTerm> in the Windows registry so that the +information will be retrieved next time the user logs in. Because it +is sometimes desirable to have system-wide as well as user-specific +mounts, there is also a system-wide mount table that all Cygwin users +inherit. The system-wide table may only be modified by a user with +the appropriate priviledges (Administrator priviledges in Windows +NT).</para> + +<para>The current user's table is located under +"HKEY_CURRENT_USER/Software/Cygnus Solutions/Cygwin/mounts +v<version>" +where <version> is the latest registry version associated with +the Cygwin library (this version is not the same as the release +number). The system-wide table is located under the same subkeys +under HKEY_LOCAL_SYSTEM.</para> + +<para>By default, the POSIX root <filename>/</filename> points to the +system partition but it can be relocated to any directory in the +Windows file system using the <command>mount</command> command. +Whenever Cygwin generates a POSIX path from a Win32 one, it uses the +longest matching prefix in the mount table. Thus, if +<filename>C:</filename> is mounted as <filename>/c</filename> and also +as <filename>/</filename>, then Cygwin would translate +<filename>C:/foo/bar</filename> to <filename>/c/foo/bar</filename>.</para> + +<para>Invoking <command>mount</command> without any arguments displays +Cygwin's current set of mount points. +In the following example, the C +drive is the POSIX root and D drive is mapped to +<filename>/d</filename>. Note that in this case, the root mount is a +system-wide mount point that is visible to all users running Cygwin +programs, whereas the <filename>/d</filename> mount is only visible +to the current user.</para> + +<example> +<title>Displaying the current set of mount points</title> +<screen> +<prompt>c:\cygnus\></prompt> <userinput>mount</userinput> +Device Directory Type Flags +D: /d user textmode +C: / system textmode +</screen> +</example> + +<para>You can also use the <command>mount</command> command to add +new mount points, and the <command>umount</command> to delete +them. See <Xref Linkend="mount"> and <Xref Linkend="umount"> for more +information on how to use these utilities to set up your Cygwin POSIX +file system.</para> + +<para>Whenever Cygwin cannot use any of the existing mounts to convert +from a particular Win32 path to a POSIX one, Cygwin will +automatically default to an imaginary mount point under the default POSIX +path <filename>/cygdrive</filename>. For example, if Cygwin accesses +<filename>Z:\foo</filename> and the Z drive is not currently in the +mount table, then <filename>Z:\</filename> would be automatically +converted to <filename>/cygdrive/Z</filename>. The default +prefix of <filename>/cygdrive</filename> may be changed (see the +<Xref Linkend="mount"> for more information).</para> + +<para>It is possible to assign some special attributes to each mount +point. Automatically mounted partitions are displayed as "auto" +mounts. Mounts can also be marked as either "textmode" or "binmode" +-- whether text files are read in the same manner as binary files by +default or not (see <Xref Linkend="using-textbinary"> for more +information on text and binary modes.</para> + +</sect2> + +<sect2><title>Cygwin Mount Table Strategies</title> + +<para>Which set of mounts is right for a given Cygwin user depends +largely on how closely you want to simulate a POSIX environment, +whether you mix Windows and Cygwin programs, and how many drive +letters you are using. If you want to be very POSIX-like (assuming +"CygwinRoot" is the top directory of your Cygwin distribution), you may +want to do something like this: + +<example><title>POSIX-like mount setup</title> +<screen> +<prompt>C:\></prompt> <userinput>mount c:\Cygnus\CygwinRoot /</userinput> +<prompt>C:\></prompt> <userinput>mount c:\ /c</userinput> +<prompt>C:\></prompt> <userinput>mount d:\ /d</userinput> +<prompt>C:\></prompt> <userinput>mount e:\ /cdrom</userinput> +</screen> +</example> + +<para>However, if you mix Windows and Cygwin programs a lot, you might +want to create an "identity" mapping, so that conversions between the +two (see <Xref Linkend="cygpath">) can be eliminated:</para> + +<example><title>Identity mount setup</title> +<screen> +<prompt>C:\></prompt> <userinput>mount c:\ \</userinput> +<prompt>C:\></prompt> <userinput>mount d:\foo /foo</userinput> +<prompt>C:\></prompt> <userinput>mount d:\bar /bar</userinput> +<prompt>C:\></prompt> <userinput>mount e:\grill /grill</userinput> +</screen> +</example> + +<para>You'd have to repeat this for all top-level subdirectories on +all drives, but then you'd always have the top-level directories +available as the same names in both systems.</para> + +</sect2> + +<sect2><title>Additional Path-related Information</title> + +<para>The <command>cygpath</command> program provides the ability to +translate between Win32 and POSIX pathnames in shell scripts. See +<Xref Linkend="cygpath"> for the details.</para> + +<para>The <EnVar>HOME</EnVar>, <EnVar>PATH</EnVar>, and +<EnVar>LD_LIBRARY_PATH</EnVar> environment variables are automatically +converted from Win32 format to POSIX format (e.g. from +<filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</filename> to +<filename>/bin</filename>, if there was a mount from that Win32 path to +that POSIX path) when a Cygwin process first starts.</para> + +<para>Symbolic links can also be used to map Win32 pathnames to POSIX. +For example, the command +<command>ln -s //pollux/home/joe/data /data</command> would have about +the same effect as creating a mount point from +<filename>//pollux/home/joe/data</filename> to <filename>/data</filename> +using <command>mount</command>, except that symbolic links cannot set +the default file access mode. Other differences are that the mapping is +distributed throughout the file system and proceeds by iteratively +walking the directory tree instead of matching the longest prefix in a +kernel table. Note that symbolic links will only work on network +drives that are properly configured to support the "system" file +attribute. Many do not do so by default (the Unix Samba server does +not by default, for example).</para> + +</sect2> + +</sect1> + +<sect1 id="using-specialnames"><title>Special filenames</title> + +<sect2> <title>DOS devices</title> + +<para>Windows filenames invalid under Windows are also invalid under +Cygwin. This means that base filenames such as +<filename>AUX</filename>, <filename>COM1</filename>, +<filename>LPT1</filename> or <filename>PRN</filename> (to name a few) +cannot be used in a regular Cygwin Windows or POSIX path, even with an +extension (<filename>prn.txt</filename>). However the special names can be +used as filename extensions (<filename>file.aux</filename>). You can use +the special names as you would under DOS, for example you can print on your +default printer with the command <command>cat filename > PRN</command> +(make sure to end with a Form Feed). +</para> + +<sect2> <Title>POSIX devices</title> +<para>There is no need to create a POSIX <filename>/dev</filename> +directory as it is simulated within Cygwin automatically. +It supports the following devices: <filename>/dev/null</filename>, +<filename>/dev/tty</filename> and +<filename>/dev/comX</filename> (the serial ports). +These devices cannot be seen with the command <command>ls /dev</command> +although commands such as <command>ls /dev/tty</command> work fine. +<comment> +FIXME: Are there other devices under /dev. What about the funny ones +mounted by default, such as /dev/fd1. What do they really do? +</comment> +</para> + +<sect2><title>The .exe extension</title> + +<para> Executable program filenames end with .exe but the .exe need +not be included in the command, so that traditional UNIX names can be +used. However, for programs that end in ".bat" and ".com", you cannot +omit the extension. +</para> + +<para>As a side effect, the <command> ls filename</command> gives +information about <filename>filename.exe</filename> if +<filename>filename.exe</filename> exists and <filename>filename</filename> +does not. In the same situation the function call +<function>stat("filename",..)</function> gives information about +<filename>filename.exe</filename>. The two files can be distinguished +by examining their inodes, as demonstrated below. +<screen> +<prompt>C:\Cygnus\></prompt> <userinput>ls * </userinput> +a a.exe b.exe +<prompt>C:\Cygnus\></prompt> <userinput>ls -i a a.exe</userinput> +445885548 a 435996602 a.exe +<prompt>C:\Cygnus\></prompt> <userinput>ls -i b b.exe</userinput> +432961010 b 432961010 b.exe +</screen> +If a shell script <filename>myprog</filename> and a program +<filename>myprog.exe</filename> coexist in a directory, the program +has precedence and is selected for execution of +<command>myprog</command>.</para> + +<para>The <command>gcc</command> compiler produces an executable named +<filename>filename.exe</filename> when asked to produce +<filename>filename</filename>. This allows many makefiles written +for UNIX systems to work well under Cygwin.</para> + +<para>Unfortunately, the <command>install</command> and +<command>strip</command> commands do distinguish between +<filename>filename</filename> and <filename>filename.exe</filename>. They +fail when working on a non-existing <filename>filename</filename> even if +<filename>filename.exe</filename> exists, thus breaking some makefiles. +This problem can be solved by writing <command>install</command> and +<command>strip</command> shell scripts to provide the extension ".exe" +when needed. +</para> +</sect2> + +<sect2><title>The @pathnames</title> +<para>To circumvent the limitations on shell line length in the native +Windows command shells, Cygwin programs expand their arguments +starting with "@" in a special way. If a file +<filename>pathname</filename> exists, the argument +<filename>@pathname</filename> expands recursively to the content of +<filename>pathname</filename>. Double quotes can be used inside the +file to delimit strings containing blank space. +Embedded double quotes must be repeated. +In the following example compare the behaviors of the bash built-in +<command>echo</command> and of the program <command>/bin/echo</command>. + +<example><title> Using @pathname</title> +<screen> +<prompt>/Cygnus$</prompt> <userinput>echo 'This is "a long" line' > mylist</userinput> +<prompt>/Cygnus$</prompt> <userinput>echo @mylist</userinput> +@mylist +<prompt>/Cygnus$</prompt> <userinput>/bin/echo @mylist</userinput> +This is a long line +<prompt>/Cygnus$</prompt> <userinput>rm mylist</userinput> +<prompt>/Cygnus$</prompt> <userinput>/bin/echo @mylist</userinput> +@mylist +</screen> +</example> +</sect2> +</sect1> diff --git a/winsup/doc/programming.sgml b/winsup/doc/programming.sgml new file mode 100644 index 000000000..45f26f4fa --- /dev/null +++ b/winsup/doc/programming.sgml @@ -0,0 +1,11 @@ +<chapter id="programming"><title>Programming with Cygwin</title> + +DOCTOOL-INSERT-gcc + +DOCTOOL-INSERT-gdb + +DOCTOOL-INSERT-dll + +DOCTOOL-INSERT-windres + +</chapter> diff --git a/winsup/doc/readme.texinfo b/winsup/doc/readme.texinfo new file mode 100644 index 000000000..ee537f63b --- /dev/null +++ b/winsup/doc/readme.texinfo @@ -0,0 +1,12 @@ +\input texinfo +@title README 20.2 for Cygwin B20.1 Release. + +@setfilename readme.txt + +@include sites.texinfo +@include install.texinfo + +@chapter Release Information +@include changes.texinfo + +@include relnotes.texinfo diff --git a/winsup/doc/relnotes.texinfo b/winsup/doc/relnotes.texinfo new file mode 100644 index 000000000..5c3020304 --- /dev/null +++ b/winsup/doc/relnotes.texinfo @@ -0,0 +1,15 @@ +@chapter Known/potential Problems in the B20.1 Release + +@section Windows 95 freezing up +While this problem may have been worse under B19, Control-c's in bash +under Win 95 may still be able to lock up the Win 95 kernel, freezing +your machine. This problem can be fixed if you are running the OSR2 +version of Win 95 by installing the USB patch available on OSR2 CDs or +on MSDN subscription CDs. More information about OSR2 and the USB patch +is available from @file{http://www.compuclinic.com/osr2faq/index.html}. + +@section Some programs can't deal with // pathname scheme in arguments +gcc and other tools aren't fully compatible with the current pathname +scheme: it can't grok an argument of -I//d/foo which means it is vital +that when attempting to configure/build UNIX packages, that only normal +paths with single slashes are used. diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml new file mode 100644 index 000000000..184233026 --- /dev/null +++ b/winsup/doc/setup-net.sgml @@ -0,0 +1,131 @@ +<chapter id="setup-net"><title>Setting Up Cygwin</title> + +<sect1><title>Cygwin Contents</title> + +<para>The following packages are included in the full release:</para> + +<para>Development tools: binutils, bison, byacc, dejagnu, diff, +expect, flex, gas, gcc, gdb, itcl, ld, libstdc++, make, patch, tcl, +tix, tk</para> + +<para>User tools: ash, bash, bzip2, diff, fileutils, findutils, gawk, +grep, gzip, less, m4, sed, shellutils, tar, textutils, time</para> + +<para>The user tools release only contains the user tools.</para> + +<para>Full source code is available for these tools.</para> + +</sect1> +<sect1><title>Installing the binary release</title> + +<para>Important! Be sure to remove any older versions of the Cygwin +tools from your <EnVar>PATH</EnVar> environment variable so you do +not execute them by mistake.</para> + +<para>Connect to one of the ftp servers listed in +<ulink URL="http://sourceware.cygnus.com/cygwin/mirrors.html"> +http://sourceware.cygnus.com/cygwin/mirrors.html</ulink> and +<command>cd</command> to the directory containing the latest release. +</para> + +<para>If you want the development tools and the programs necessary to +run the GNU configure mechanism, you should download the full binary +release called <filename>full.exe</filename>. If you only care +about the user tools listed above, download +<filename>usertools.exe</filename> instead.</para> + +<para>If you have an unreliable connection, download the appropriate +binary in smaller chunks instead. For the split full installer, get +the files in the `full-split' subdirectory. Once downloaded, +combine the split files at the command prompt by doing a:</para> + +<screen> +<prompt>C:\Cygnus\></prompt><userinput>copy /b xaa + xab + xac + ... + xak + xal full.exe</userinput> +<prompt>C:\Cygnus\></prompt><userinput>del xa*.*</userinput> +</screen> + +<para>A similar process can be used for the user tools.</para> + +<para>Once you have installed the executable on your system, run +it. First off, the installer will prompt you for a location to extract +the temporary files it needs to install the release on your +system. The default should be fine for most people.</para> + +<para>Next it will ask you to choose an install location. The default is +<filename><replaceable>system-drive</replaceable>:\cygnus\cygwin-b20</filename>. +Feel free to choose another location if you would prefer.</para> + +<para>Finally, it will ask you for the name of the Program Files +folder shortcut to add. By default, the installer will create a +`Cygwin B20' entry in a folder called `Cygnus Solutions'. When this +step is completed, it will install the tools and exit.</para> + +<para>If you should ever want to uninstall the tools, you may do so +via the "Add/Remove Programs" control panel.</para> + +<para> At this point you should be able to look under the start menu and +select "Cygwin Beta 20" (or whatever you named it). This will pop up a bash +shell with special environment variables set up for you. If you are running +Windows 95 or 98 and are faced with the error message "Out of environment +space", you need to increase the amount of environment space. Adding the +line <command>shell=C:\command.com /e:4096 /p</command> to the file +<filename>C:\CONFIG.SYS</filename> and then rebooting should do the trick if +<filename>C:</filename> is your system drive letter.</para> + +<para>If you want to install the sources follow the +instructions in the next section, else go directly to +<Xref LinkEnd="setup-dir"> to complete your system setup.</para> + +</sect1> +<sect1><title>Installing the source code</title> + +<para>Before downloading the source code corresponding to the release, +you should install the latest release of the tools (either the full +release or just the user tools).</para> + +<para>Create the directory that will house the source code. +<command>cd</command> there.</para> + +<para>Connect to one of the ftp servers listed above and +<command>cd</command> to the directory containing the latest release. +</para> + +<para>The source code is split into two units: user tools and development +tools. If you want the user tools source code, <command>cd</command> into +the <filename>user-src-split</filename> subdirectory. Download the files +there. If you want the development tools sources, <command>cd</command> +into the <filename>dev-src-split</filename> subdirectory. Download the +files there.</para> + +<para>Back in the Windows command shell, for the user tools +source:</para> + +<screen> +<prompt>C:\Cygnus\></prompt> <userinput>copy /b xba + xbb + xbc + xbd + xbe + xbf + xbg user-src.tar.bz2</userinput> +<prompt>C:\Cygnus\></prompt> <userinput>del xb*.*</userinput> +<prompt>C:\Cygnus\></prompt> <userinput>bunzip2 user-src.tar.bz2</userinput> +<prompt>C:\Cygnus\></prompt> <userinput>tar xvf user-src.tar</userinput> +</screen> + +<para>For the development tools source:</para> + +<screen> +<prompt>C:\Cygnus\></prompt> <userinput>copy /b xca + xcb + xcc + xcd + ... + xck + xcl dev-src.tar.bz2</userinput> +<prompt>C:\Cygnus\></prompt> <userinput>del xc*.*</userinput> +<prompt>C:\Cygnus\></prompt> <userinput>bunzip2 dev-src.tar.bz2</userinput> +<prompt>C:\Cygnus\></prompt> <userinput>tar xvf dev-src.tar</userinput> +</screen> + +<para>Both will expand into a directory called +<filename>src</filename>.</para> + +<para>Note: if you want the sources corresponding to everything in the +full.exe binary installer, you will need to download and expand both +the <filename>user-src.tar.bz2</filename> and +<filename>dev-src.tar.bz2</filename> source archives!</para> +</sect1> + +DOCTOOL-INSERT-setup-dir +DOCTOOL-INSERT-setup-env +DOCTOOL-INSERT-setup-files +</chapter> diff --git a/winsup/doc/setup.sgml b/winsup/doc/setup.sgml new file mode 100644 index 000000000..2e6ce2857 --- /dev/null +++ b/winsup/doc/setup.sgml @@ -0,0 +1,42 @@ +<chapter id="setup"><title>Setting Up Cygwin</title> + +<sect1><title>Cygwin Contents</title> + +<para>The following packages are included in the native Win32 +release of GNUPro:</para> + +<para>GNUPro development tools: binutils, bison, byacc, dejagnu, +diff, expect, flex, gas, gcc, gdb, itcl, ld, libstdc++, make, patch, +tcl, tix, tk</para> + +<para>GNUPro unsupported tools: ash, bash, bzip2, diff, fileutils, +findutils, gawk, grep, gzip, m4, sed, shellutils, tar, textutils, +time</para> + +<sect1><title>Installing the binary release</title> + +<para>Load the GNUPro CD-ROM and run the installer. It will +take you through the installation process, starting with asking for +your install location. Once the installation is complete, there will +be a new Program Files folder that you can use to obtain a shell +from which you can run the tools.</para> + +<para>There are two remaining thing you should do from this +prompt. First, you need to type <command>mkdir -p /tmp</command> to +ensure that a temp directory exists for programs that expect to find +one there.</para> + +<para>Second, depending on how you intend to use the tools, various +programs may need to be able to find `/bin/sh'. You should `mkdir -p +/bin' and put a copy of `sh.exe' there, removing the older version, if +present. Note that you can use the `mount' utility to select which +drive letter is mounted as `/'.</para> + +<para>If you should ever want to uninstall the tools, you may do so +via the "Add/Remove Programs" control panel.</para> + +DOCTOOL-INSERT-setup-dir +DOCTOOL-INSERT-setup-env +DOCTOOL-INSERT-setup-reg +DOCTOOL-INSERT-setup-mount +</chapter> diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml new file mode 100644 index 000000000..7a24e5fa1 --- /dev/null +++ b/winsup/doc/setup2.sgml @@ -0,0 +1,279 @@ +<sect1 id="setup-dir"><title>Directory Structure</title> + +<para> +Cygwin knows how to emulate a standard UNIX directory structure, to +some extent. This is done through the use of mount tables that map +Win32 paths to POSIX ones. The mount table may be set up and modified +with the <command>mount</command> command. This section explains how +to properly organize the structure. </para> + +<para> When you set up the system you should decide where you want the +root to be mapped. Possible choices are the root of your Windows +system, such as +<filename>c:</filename> or a directory such as +<filename>c:\progra~1\root</filename>. +</para> + +<para> +Execute the following commands inside bash as it is difficult to +change the position of the root from the Windows command prompt. +Changing the mount points may invalidate <EnVar>PATH</EnVar>, if this +happens simply exit and relaunch bash. Create the directory if +needed, then <command>umount /</command> the current root and +<command>mount</command> it in its new place. You also have to decide if +you want to use text or binary mode. +</para> + +<para> +Next, create the traditional main UNIX directories, with +the following command (in some shells it is necessary to issue +separate <command>mkdir</command> commands, each with a single +argument). +</para> + +<screen> +<prompt>/$</prompt> <userinput>mkdir /tmp /bin /etc /var /usr</userinput> +</screen> + +<para> +Next we will initialize the content of these directories. +</para> + +<para> +You should make sure that you always have a valid +<filename>/tmp</filename> directory. If you want to avoid creating a +real <filename>/tmp</filename>, you can use the +<command>mount</command> utility to point <filename>/tmp</filename> to +another directory, such as <filename>c:\tmp</filename>, or create a +symbolic link <filename>/tmp</filename> to point to such a directory. +</para> + +<para> +The <filename>/bin</filename> directory should contain the shell +<filename>sh.exe</filename>. You have three choices. The first is to +copy this program from the Cygnus <filename>bin</filename> directory. +The second is to use <command>mount</command> to mount the Cygnus +<filename>bin</filename> directory to <filename>/bin</filename> (the +advantage of this approach is that your <envar>PATH</envar> will be +shorter inside bash). The third is to make <filename>/bin</filename> a +symbolic link to the Cygnus <filename>bin</filename> directory. +</para> + +<para> +Note that Cygwin comes with two shells: <command>bash.exe</command> and +<command>sh.exe</command>, which is based on <command>ash</command>. The +system is faster when <command>ash</command> is used as the +non-interactive shell. +The only functionality supported in <command>ash</command> is that +of the traditional <command>sh</command>. +In case of trouble with <command>ash</command> make +<command>sh.exe</command> point to <command>bash.exe</command>. +</para> + +<para> +We now turn to <filename>/etc</filename>. You may want to copy in it +the <filename>termcap</filename> file from the Cygnus +<filename>etc</filename> directory, although the defaults built into +the programs suffice for the normal console. You may also use +<command>mount</command> or create as symbolic link to the Cygnus +<filename>etc</filename>, just as for <filename>/bin</filename> +above. +</para> + +<para> Under Windows NT, if you want to create +<filename>/etc/passwd</filename> and <filename>/etc/group</filename> +(i.e. so that <command>whoami</command> works and +<command>ls -l</command> replaces the UID with a name) just +do this: +</para> + +<screen> +<prompt>/$</prompt> <userinput>cd /etc</userinput> +<prompt>/etc$</prompt> <userinput>mkpasswd -l > /etc/passwd</userinput> +<prompt>/etc$</prompt> <userinput>mkgroup -l > /etc/group</userinput> +</screen> + +<para> Future changes to your NT registry will NOT be reflected in +<filename>/etc/passwd</filename> or <filename>/etc/group </filename> after +this so you may want to regenerate these files periodically. Under Windows +9x, you can create and edit these files with a text editor. </para> + +<para> +The <command>who</command> command requires the +<filename>/var/run/utmp</filename> to exist. +Create it if you wish. +The system also logs information in <filename>/var/log/wtmp</filename>, +if it exists. +</para> + +<para> +The <filename>/usr</filename> directory is not used by the Cygwin +system but it is a standard place to install optional packages. +</para> + +<para> +You may also want to mount directories such as <filename>/a</filename> +and <filename>/d</filename> to refer to your local and network drives. +</para> + +<para> +You do not need to create <filename>/dev</filename> in order to set up +mounts for devices such as <filename>/dev/null</filename> as these +are already automatically simulated inside the Cygwin library. +</para> + +</sect1> + +<sect1 id="setup-env"><title>Environment Variables</title> + +<para> +Before starting bash, you must set some environment variables, some of +which can also be set or modified inside bash. Cygnus provides you +with a .bat file where the most important ones are set before bash in +launched. This is the safest way to launch bash initially. The .bat +file is installed by default in +<filename>\cygnus\cygwin-b20/cygnus.bat</filename> and pointed to in +the Start Menu. You can edit it to your liking. +</para> + +<para> +The <envar>CYGWIN</envar> variable is used to configure many global +settings for the Cygwin +runtime system. Initially you can leave <envar>CYGWIN</envar> unset +or set it to <literal>tty</literal> (e.g. to support job control with ^Z +etc...) using a syntax like this in the DOS shell, before launching bash. +</para> + +<screen> +<prompt>C:\Cygnus\></prompt> <userinput>set CYGWIN=tty notitle strace=0x1</userinput> +</screen> + +<para> +The <envar>PATH</envar> environment variable is used by Cygwin +applications as a list of directories to search for executable files +to run. This environment variable is converted from Windows format +(e.g. <filename>C:\WinNT\system32;C:\WinNT</filename>) to UNIX format +(e.g., <filename>/WinNT/system32:/WinNT</filename>) when a Cygwin +process first starts. +Set it so that it contains at least the Cygnus +<filename>bin</filename> directory +<filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</filename> before +launching bash. +</para> + +<para> +The <envar>HOME</envar> environment variable is used by many programs to +determine the location of your home directory and we recommend that it be +defined. This environment variable is also converted from Windows format +when a Cygwin process first starts. Set it to point to your home directory +before launching bash. +</para> + +<para> +<command>make</command> uses an environment variable +<envar>MAKE_MODE</envar> to decide if it uses +<filename>command.com</filename> or <filename>/bin/sh</filename> to +run command lines. If you are getting strange errors from +<command>make</command> about "/c not found", set +<envar>MAKE_MODE</envar> to <literal>UNIX</literal> at the command +prompt or in bash. +</para> + +<screen> +<prompt>C:\Cygnus\></prompt> <userinput>set MAKE_MODE=UNIX</userinput> + +<prompt>/Cygnus$</prompt> <userinput>export MAKE_MODE=UNIX</userinput> +</screen> + +<para> +The <envar>TERM</envar> environment variable specifies your terminal +type. You can set it to <literal>cygwin</literal>. +</para> + +<para>The <envar>LD_LIBRARY_PATH</envar> environment variable is +used by the Cygwin function <function>dlopen ()</function> as a list +of directories to search for .dll files to load. This environment +variable is converted from Windows format to UNIX format +when a Cygwin process first starts. +Most Cygwin applications do not make use of the +<function>dlopen ()</function> call and do not need this variable. +</para> + +</sect1> + +<sect1 id="setup-files"><title>Customizing bash</title> + +<para> +To set bash up so that cut and paste work properly, click on the +"Properties" button of the window, then on the "Misc" tab. Make sure +that "Quick Edit" is checked and "Fast Pasting" isn't. These settings +will be remembered next time you run bash from that +shortcut. Similarly you can set the working directory inside the +"Program" tab. The entry "%HOME%" is valid. +</para> + +<para> +Your home directory should contain three initialization files +that control the behavior of bash. They are +<filename>.profile</filename>, <filename>.bashrc</filename> and +<filename>.inputrc</filename>. These initialization files will only +be read if <envar>HOME</envar> is defined before starting bash. +</para> + +<para> +<filename>.profile</filename> (other names are also valid, see the bash man +page) contains bash commands. It is executed when bash is started as login +shell, e.g. from the command <command>bash --login</command> (the provided +.bat file does not set the switch). This is a useful place to define and +export environment variables and bash functions that will be used by bash +and the programs invoked by bash. It is a good place to redefine +<envar>PATH</envar> if needed. We recommend adding a ":." to the end of +<envar>PATH</envar> to also search the current working directory (contrary +to DOS, the local directory is not searched by default). Also to avoid +delays you should either <command>unset</command> <envar>MAILCHECK</envar> +or define <envar>MAILPATH</envar> to point to your existing mail inbox. +</para> + +<para> +<filename>.bashrc</filename> is similar to +<filename>.profile</filename> but is executed each time an interactive +bash shell is launched. It serves to define elements that are not +inherited through the environment, such as aliases. If you do not use +login shells, you may want to put the contents of +<filename>.profile</filename> as discussed above in this file +instead. +</para> + +<para> +<screen> +shopt -s nocaseglob +</screen> +will allow bash to glob filenames in a case-insensitive manner. +Note that <filename>.bashrc</filename> is not called automatically for login +shells. You can source it from <filename>.profile</filename>. +</para> + +<para> +<filename>.inputrc</filename> controls how programs using the readline +library (including bash) behave. It is loaded automatically. The +full details are in the <filename>readline.info</filename>. +Due to a bug in the current readline version, +<filename>.inputrc</filename> cannot contain \r, +even on text mounted systems. +Consider the following settings: +<screen> +# Make Bash 8bit clean +set meta-flag on +set convert-meta off +set output-meta on +# Ignore case while completing +set completion-ignore-case on +</screen> +<para>The first three commands allow bash to display 8-bit characters, +useful for languages with accented characters. The last line makes +filename completion case insensitive, which can be convenient in a +Windows environment. +</para> + +</sect1> + diff --git a/winsup/doc/textbinary.sgml b/winsup/doc/textbinary.sgml new file mode 100644 index 000000000..cf6fc1b36 --- /dev/null +++ b/winsup/doc/textbinary.sgml @@ -0,0 +1,181 @@ +<sect1 id="using-textbinary"><title>Text and Binary modes</title> + +<sect2> <title>The Issue</title> + +<para>On a UNIX system, when an application reads from a file it gets +exactly what's in the file on disk and the converse is true for writing. +The situation is different in the DOS/Windows world where a file can +be opened in one of two modes, binary or text. In the binary mode the +system behaves exactly as in UNIX. However in text mode there are +major differences:</para> +<OrderedList Numeration="Loweralpha" Spacing="Compact"> +<listitem> +<para> +On writing in text mode, a NL (\n, ^J) is transformed into the +sequence CR (\r, ^M) NL.</para> +</listitem> +<listitem> +<para> +On reading in text mode, a CR followed by an NL is deleted and a ^Z +character signals the end of file.</para> +</listitem> +</OrderedList> + +<para>This can wreak havoc with the seek/fseek calls since the number +of bytes actually in the file may differ from that seen by the +application.</para> + +<para>The mode can be specified explicitly as explained in the Programming +section below. In an ideal DOS/Windows world, all programs using lines as +records (such as <command>bash</command>, <command>make</command>, +<command>sed</command> ...) would open files (and change the mode of their +standard input and output) as text. All other programs (such as +<command>cat</command>, <command>cmp</command>, <command>tr</command> ...) +would use binary mode. In practice with Cygwin, programs that deal +explicitly with object files specify binary mode (this is the case of +<command>od</command>, which is helpful to diagnose CR problems). Most +other programs (such as <command>cat</command>, <command>cmp</command>, +<command>tr</command>) use the default mode.</para> + +</sect2> + +<sect2><title>The default Cygwin behavior</title> + +<para>The Cygwin system gives us some flexibility in deciding how files +are to be opened when the mode is not specified explicitly. +The rules are evolving, this section gives the design goals.</para> +<OrderedList Numeration="Loweralpha"> +<listitem> +<para>If the file appears to reside on a file system that is mounted +(i.e. if its pathname starts with a directory displayed by +<command>mount</command>), then the default is specified by the mount +flag. If the file is a symbolic link, the mode of the target file system +applies.</para> +</listitem> +<listitem> +<para>If the file appears to reside on a file system that is not mounted +(as can happen when the path contains a drive letter), the default is text. +</para> +</listitem> +<listitem> +<para>Pipes and non-file devices are opened in binary mode, +except if the <EnVar>CYGWIN</EnVar> environment variable contains +<literal>nobinmode</literal>.</para> +<warning><Title>Warning!</Title><para>In b20.1 of 12/98, a file will be opened +in binary mode if any of the following conditions hold:</para> +<OrderedList Numeration="arabic" Spacing="Compact"> +<listitem><para>binary mode is specified in the open call</para> +</listitem> +<listitem><para><envar>CYGWIN</envar> contains <literal>binmode</literal></para> +</listitem> +<listitem><para>the file resides in a binary mounted partition</para> +</listitem> +<listitem><para>the file is not a disk file</para> +</listitem> +</OrderedList> +</warning> +</listitem> + +<listitem> +<para>When a Cygwin program is launched by a shell, its standard input, +output and error are in binary mode if the <envar>CYGWIN</envar> variable +contains <literal>tty</literal>, else in text mode, except if they are piped +or redirected.</para> +<para> When redirecting, the Cygwin shells uses rules (a-c). For +these shells the relevant value of <envar>CYGWIN</envar> is that at the time +the shell was launched and not that at the time the program is executed. +Non-Cygwin shells always pipe and redirect with binary mode. With +non-Cygwin shells the commands <command> cat filename | program </command> +and <command> program < filename </command> are not equivalent when +<filename>filename</filename> is on a text-mounted partition. </para> +</listitem> +</OrderedList> +</sect2> + +<sect2><title>Example</title> +<para>To illustrate the various rules, we provide scripts to delete CRs +from files by using the <command>tr</command> program, which can only write +to standard output. +The script</para> +<screen> +#!/bin/sh +# Remove \r from the file given as argument +tr -d '\r' < "$1" > "$1".nocr +</screen> +<para> will not work on a text mounted systems because the \r will be +reintroduced on writing. However scripts such as </para> +<screen> +#!/bin/sh +# Remove \r from the file given as argument +tr -d '\r' | gzip | gunzip > "$1".nocr +</screen> +<para>and the .bat file</para> +<screen> +REM Remove \r from the file given as argument +@echo off +tr -d \r < %1 > %1.nocr +</screen> +<para> work fine. In the first case (assuming the pipes are binary) +we rely on <command>gunzip</command> to set its output to binary mode, +possibly overriding the mode used by the shell. +In the second case we rely on the DOS shell to redirect in binary mode. +</para> +</sect2> + +<sect2><title>Binary or text?</title> + +<para>UNIX programs that have been written for maximum portability +will know the difference between text and binary files and act +appropriately under Cygwin. For those programs, the text mode default +is a good choice. Programs included in official Cygnus distributions +should work well in the default mode. </para> + +<para>Text mode makes it much easier to mix files between Cygwin and +Windows programs, since Windows programs will usually use the CRLF +format. Unfortunately you may still have some problems with text +mode. First, some of the utilities included with Cygwin do not yet +specify binary mode when they should, e.g. <command>cat</command> will +not work with binary files (input will stop at ^Z, CRs will be +introduced in the output). Second, you will introduce CRs in text +files you write, which can cause problems when moving them back to a +UNIX system. </para> + +<para>If you are mounting a remote file system from a UNIX machine, +or moving files back and forth to a UNIX machine, you may want to +access the files in binary mode. The text files found there will normally +be in UNIX NL format, and you would want any files put there by Cygwin +programs to be stored in a format understood by UNIX. +Be sure to remove CRs from all Makefiles and +shell scripts and make sure that you only edit the files with +DOS/Windows editors that can cope with and preserve NL terminated lines. +</para> + +<para>Note that you can decide this on a disk by disk basis (for +example, mounting local disks in text mode and network disks in binary +mode). You can also partition a disk, for example by mounting +<filename>c:</filename> in text mode, and <filename>c:\home</filename> +in binary mode.</para> + +</sect2> + +<sect2><title>Programming</title> + +<para>In the <function>open()</function> function call, binary mode can be +specified with the flag <literal>O_BINARY</literal> and text mode with +<literal>O_TEXT</literal>. These symbols are defined in +<filename>fcntl.h</filename>.</para> + +<para>In the <function>fopen()</function> function call, binary mode can be +specified by adding a <literal>b</literal> to the mode string. There is no +direct way to specify text mode.</para> + +<para>The mode of a file can be changed by the call +<function>setmode(fd,mode)</function> where <literal>fd</literal> is a file +descriptor (an integer) and <literal>mode</literal> is +<literal>O_BINARY</literal> or <literal>O_TEXT</literal>. The function +returns <literal>O_BINARY</literal> or <literal>O_TEXT</literal> depending +on the mode before the call, and <literal>EOF</literal> on error.</para> + +</sect2> + +</sect1> diff --git a/winsup/doc/using.sgml b/winsup/doc/using.sgml new file mode 100644 index 000000000..9d60e77bf --- /dev/null +++ b/winsup/doc/using.sgml @@ -0,0 +1,19 @@ +<chapter id="using"><title>Using Cygwin</title> + +<para>This chapter explains some key differences between the Cygwin +environment and traditional UNIX systems. It assumes a working +knowledge of standard UNIX commands.</para> + +DOCTOOL-INSERT-using-pathnames + +DOCTOOL-INSERT-using-textbinary + +DOCTOOL-INSERT-using-filemodes + +DOCTOOL-INSERT-using-specialnames + +DOCTOOL-INSERT-using-cygwinenv + +DOCTOOL-INSERT-using-utils + +</chapter> diff --git a/winsup/doc/what.texinfo b/winsup/doc/what.texinfo new file mode 100644 index 000000000..dd55f0fde --- /dev/null +++ b/winsup/doc/what.texinfo @@ -0,0 +1,85 @@ +@chapter What is it? + +The Cygwin tools are ports of the popular GNU development tools +for Windows NT, 95, and 98. They run thanks to the Cygwin library which +provides the UNIX system calls and environment these programs expect. + +With these tools installed, it is possible to write Win32 console or +GUI applications that make use of the standard Microsoft Win32 API +and/or the Cygwin API. As a result, it is possible to easily +port many significant Unix programs without the need +for extensive changes to the source code. This includes configuring +and building most of the available GNU software (including the packages +included with the Cygwin development tools themselves). Even if +the development tools are of little to no use to you, you may have +interest in the many standard Unix utilities provided with the package. +They can be used both from the bash shell (provided) or from the +standard Windows command shell. + +@section Is it free software? + +Yes. Parts are GNU software (gcc, gas, ld, etc...), parts are covered +by the standard X11 license, some of it is public domain, some of +it was written by Cygnus and placed under the GPL. None of it is +shareware. You don't have to pay anyone to use it but you should be +sure to read the copyright section of the FAQ more more information on +how the GNU General Public License may affect your use of these tools. + +In particular, if you intend to port a proprietary (non-GPL'd) +application using Cygwin, you will need the proprietary-use license +for the Cygwin library. This is available for purchase; please +contact sales@@cygnus.com for more information. +All other questions should be sent to the project +mailing list cygwin@@sourceware.cygnus.com. + +Note that when we say "free" we mean freedom, not price. The goal of +such freedom is that the people who use a given piece of software +should be able to change it to fit their needs, learn from it, share +it with their friends, etc. The Cygwin license allows you those +freedoms, so it is free software. + +The Cygwin 1.0 product is a "commercial" distribution of cygwin. As +such, it includes such non-software things as printed manuals, +support, and aggregation of useful utilities. There is nothing +(software-wise) in there that you can't already get off the net +already, if you take the time to find and download everything (and +usually, build it yourself). We test it all to make sure it works +together, and package it in a convenient form. We consider such +testing and packaging to be a valuable service and thus charge a fee +for it. Plus, it provides income for the cygwin project so we can +continue working on it :-) + +@section A brief history of the project + +The first thing done was to enhance the development tools (gcc, gdb, +gas, et al) so that they could generate/interpret Win32 native object +files. + +The next task was to port the tools to Win NT/95. We could have done +this by rewriting large portions of the source to work within the +context of the Win32 API. But this would have meant spending a huge +amount of time on each and every tool. Instead, we took a substantially +different approach by writing a shared library (cygwin.dll) that adds +the necessary unix-like functionality missing from the Win32 API (fork, +spawn, signals, select, sockets, etc.). We call this new interface the +Cygwin API. Once written, it was possible to build working Win32 +tools using unix-hosted cross-compilers, linking against this library. + +From this point, we pursued the goal of producing native tools capable of +rebuilding themselves under Windows 95 and NT (this is often +called self-hosting). Since neither OS ships with standard UNIX +user tools (fileutils, textutils, bash, etc...), we had to get the +GNU equivalents working with the Cygwin API. Most of these tools were +previously only built natively so we had to modify their configure +scripts to be compatible with cross-compilation. Other than the +configuration changes, very few source-level changes had to be made. +Running bash with the development tools and user tools in place, +Windows 95 and NT look like a flavor of UNIX from the perspective of the +GNU configure mechanism. Self hosting was achieved as of the beta 17.1 +release. + +After adding Windows 98 support to Cygwin in mid-1998, we added support +for the native Microsoft libraries in the compiler which allows +compilation of executables that do not use Cygwin. This is important to +those people who want to use the tools to develop Win32 applications +that do not need the UNIX emulation layer. diff --git a/winsup/doc/who.texinfo b/winsup/doc/who.texinfo new file mode 100644 index 000000000..a15d090ac --- /dev/null +++ b/winsup/doc/who.texinfo @@ -0,0 +1,71 @@ +@chapter Who's behind the project? + +Chris Faylor (cgf@@cygnus.com) is behind many of the recent +changes in Cygwin. Prior to joining Cygnus, he contributed significant +fixes to the process control and environ code, reworked the strace +mechanism, and rewrote the signal-related code from scratch as a Net +contributor. In addition to continuing to make technical contributions, +Chris is also currently the group's manager. + +Geoffrey Noer (noer@@cygnus.com) took over the Cygwin project from its' +initial author Steve Chamberlain in mid-1996. As maintainer, he +produced Net releases beta 16 through 20; made the development +snapshots; worked with Net contributors to fix bugs; made many various +code improvements himself; wrote a paper on Cygwin for the +1998 Usenix NT Symposium; authored the project WWW pages, FAQ, README; +etc. + +DJ Delorie (dj@@cygnus.com) has done important work in profiling Cygwin, +worked on the Dejagnu automated testing framework, merged the dlltool +functionality into ld, wrote a good deal of the Cygwin Users' Guide, +authored the cygcheck utility, and made automated snapshots available +from our project WWW page. + +Steve Chamberlain (sac@@transmeta.com) designed and implemented +Cygwin in 1995-1996 while working for Cygnus. He worked with the Net +to improve the technology, ported/integrated many of the user tools +for the first time to Cygwin, and produced all of the releases up to +beta 14. + +Marco Fuykschot (marco@@ddi.nl) and Peter Boncz (boncz@@ddi.nl) of +Data Distilleries contributed nearly all of the changes required to +make Cygwin thread-safe. They also provided the pthreads interface. + +Sergey Okhapkin (sos@@prospect.com.ru) has been an invaluable Net +contributor. He implemented the tty/pty support, has played a +significant role in revamping signal and exception handling, and has +made countless contributions throughout the library. He also provided +binaries of the development snapshots to the Net after the beta 19 +release. + +Mumit Khan (khan@@xraylith.wisc.edu) has been most helpful on the EGCS +end of things, providing quite a large number of stabilizing patches to +the compiler tools for the B20 release. + +Corinna Vinschen <corinna@@vinschen.de> has contributed several +useful fixes to the path handling code, console support, improved security +handling, and raw device support. + +Philippe Giacinti (giac@@dalim.de) contributed the implementation of +dlopen, dlclose, dlsym, dlfork, and dlerror in Cygwin. + +Many other people at Cygnus have made important contributions to Cygwin. +Tobin Brockett wrote the InstallShield-based installer for the beta 19 +and 20 releases. Ian Lance Taylor did a much-needed rework of the path +handling code for beta 18, and has made many assorted fixes throughout +the code. Jeremy Allison made significant contributions in the area of +file handling and process control, and rewrote select from scratch. +Doug Evans rewrote the path-handling code in beta 16, among other +things. Kim Knuttila and Michael Meissner put in many long hours +working on the now-defunct PowerPC port. Jason Molenda and Mark Eichin +have also made important contributions. + +Please note that those of us here at Cygnus that work on Cygwin try to +be as responsive as possible and deal with patches and questions as we +get them, but realistically we don't have time to answer all of the +email that is sent to the main mailing list. Making Net releases of the +Win32 tools and helping people on the Net out is not our primary job +function, so some email will have to go unanswered. + +Many thanks to everyone using the tools for their many contributions in +the form of advice, bug reports, and code fixes. Keep them coming! diff --git a/winsup/doc/windres.sgml b/winsup/doc/windres.sgml new file mode 100644 index 000000000..2d5410639 --- /dev/null +++ b/winsup/doc/windres.sgml @@ -0,0 +1,167 @@ + +<sect1 id="windres"><title>Defining Windows Resources</title> + +<para><filename>windres</filename> reads a Windows resource file +(<filename>*.rc</filename>) and converts it to a res or coff file. +The syntax and semantics of the input file are the same as for any +other resource compiler, so please refer to any publication describing +the Windows resource format for details. Also, the +<filename>windres</filename> program itself is fully documented in the +Binutils manual. Here's an example of using it in a project:</para> + +<screen> +myapp.exe : myapp.o myapp.res + gcc -mwindows myapp.o myapp.res -o $@ + +myapp.res : myapp.rc resource.h + windres $< -O coff -o $@ +</screen> + + +<para>What follows is a quick-reference to the syntax +<filename>windres</filename> supports.</para> + +<screen> + +id ACCELERATORS suboptions +BEG +"^C" 12 +"Q" 12 +65 12 +65 12 , VIRTKEY ASCII NOINVERT SHIFT CONTROL ALT +65 12 , VIRTKEY, ASCII, NOINVERT, SHIFT, CONTROL, ALT +(12 is an acc_id) +END + +SHIFT, CONTROL, ALT require VIRTKEY + + +id BITMAP memflags "filename" +memflags defaults to MOVEABLE + + +id CURSOR memflags "filename" +memflags defaults to MOVEABLE,DISCARDABLE + + +id DIALOG memflags exstyle x,y,width,height styles BEG controls END +id DIALOGEX memflags exstyle x,y,width,height styles BEG controls END +id DIALOGEX memflags exstyle x,y,width,height,helpid styles BEG controls END + +memflags defaults to MOVEABLE +exstyle may be EXSTYLE=number +styles: CAPTION "string" + CLASS id + STYLE FOO | NOT FOO | (12) + EXSTYLE number + FONT number, "name" + FONT number, "name",weight,italic + MENU id + CHARACTERISTICS number + LANGUAGE number,number + VERSIONK number +controls: + AUTO3STATE params + AUTOCHECKBOX params + AUTORADIOBUTTON params + BEDIT params + CHECKBOX params + COMBOBOX params + CONTROL ["name",] id, class, style, x,y,w,h [,exstyle] [data] + CONTROL ["name",] id, class, style, x,y,w,h, exstyle, helpid [data] + CTEXT params + DEFPUSHBUTTON params + EDITTEXT params + GROUPBOX params + HEDIT params + ICON ["name",] id, x,y [data] + ICON ["name",] id, x,y,w,h, style, exstyle [data] + ICON ["name",] id, x,y,w,h, style, exstyle, helpid [data] + IEDIT params + LISTBOX params + LTEXT params + PUSHBOX params + PUSHBUTTON params + RADIOBUTTON params + RTEXT params + SCROLLBAR params + STATE3 params + USERBUTTON "string", id, x,y,w,h, style, exstyle +params: + ["name",] id, x, y, w, h, [data] + ["name",] id, x, y, w, h, style [,exstyle] [data] + ["name",] id, x, y, w, h, style, exstyle, helpid [data] + +[data] is optional BEG (string|number) [,(string|number)] (etc) END + + +id FONT memflags "filename" +memflags defaults to MOVEABLE|DISCARDABLE + +id ICON memflags "filename" +memflags defaults to MOVEABLE|DISCARDABLE + +LANGUAGE num,num + +id MENU options BEG items END +items: + "string", id, flags + SEPARATOR + POPUP "string" flags BEG menuitems END +flags: + CHECKED + GRAYED + HELP + INACTIVE + MENUBARBREAK + MENUBREAK + +id MENUEX suboptions BEG items END +items: + MENUITEM "string" + MENUITEM "string", id + MENUITEM "string", id, type [,state] + POPUP "string" BEG items END + POPUP "string", id BEG items END + POPUP "string", id, type BEG items END + POPUP "string", id, type, state [,helpid] BEG items END + +id MESSAGETABLE memflags "filename" +memflags defaults to MOVEABLE + +id RCDATA suboptions BEG (string|number) [,(string|number)] (etc) END + +STRINGTABLE suboptions BEG strings END +strings: + id "string" + id, "string" + +(User data) +id id suboptions BEG (string|number) [,(string|number)] (etc) END + +id VERSIONINFO stuffs BEG verblocks END +stuffs: FILEVERSION num,num,num,num + PRODUCTVERSION num,num,num,num + FILEFLAGSMASK num + FILEOS num + FILETYPE num + FILESUBTYPE num +verblocks: + BLOCK "StringFileInfo" BEG BLOCK BEG vervals END END + BLOCK "VarFileInfo" BEG BLOCK BEG vertrans END END +vervals: VALUE "foo","bar" +vertrans: VALUE num,num + + + +suboptions: + memflags + CHARACTERISTICS num + LANGUAGE num,num + VERSIONK num + +memflags are MOVEABLE/FIXED PURE/IMPURE PRELOAD/LOADONCALL DISCARDABLE + +</screen> + +</sect1> |