diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml index daaba9ac4..2cbec03bb 100644 --- a/winsup/utils/utils.sgml +++ b/winsup/utils/utils.sgml @@ -120,8 +120,9 @@ identical to -w and -s together. Caveat: The -l option does not work if the -check_case parameter of CYGWIN is set to strict, -since Cygwin is not able to match any Windows short path in this mode. +check_case parameter of CYGWIN +is set to strict, since Cygwin is not able to match +any Windows short path in this mode. The -p option means that you want to convert @@ -169,16 +170,110 @@ other formats. +dumper + + +Usage: dumper [OPTION] FILENAME WIN32PID +Dump core from WIN32PID to FILENAME.core +-d, --verbose be verbose while dumping +-h, --help output help information and exit +-q, --quiet be quiet while dumping (default) +-v, --version output version information and exit + + +The dumper utility can be used to create a +core dump of running Windows process. This core dump can be later loaded +to gdb and analyzed. One common way to use +dumper is to plug it into cygwin's Just-In-Time +debugging facility by adding + + +error_start=x:\path\to\dumper.exe + + +to the CYGWIN environment variable. Please note that +x:\path\to\dumper.exe is Windows-style and not cygwin +path. If error_start is set this way, then dumper will +be started whenever some program encounters a fatal error. + + + +dumper can be also be started from the command line to +create a core dump of any running process. Unfortunately, because of a Windows +API limitation, when a core dump is created and dumper +exits, the target process is terminated too. + + + +To save space in the core dump, dumper doesn't write those +portions of target process' memory space that are loaded from executable and +dll files and are unchangeable, such as program code and debug info. Instead, +dumper saves paths to files which contain that data. When a +core dump is loaded into gdb, it uses these paths to load appropriate files. +That means that if you create a core dump on one machine and try to debug it on +another, you'll need to place identical copies of the executable and dlls in +the same directories as on the machine where the core dump was created. + + + + +getfacl + + +Usage: getfacl [-adn] FILE [FILE2...] +Display file and directory access control lists (ACLs). + + -a, --all display the filename, the owner, the group, and + the ACL of the file + -d, --dir display the filename, the owner, the group, and + the default ACL of the directory, if it exists + -h, --help output usage information and exit + -n, --noname display user and group IDs instead of names + -v, --version output version information and exit + +When multiple files are specified on the command line, a blank +line separates the ACLs for each file. + + + +For each argument that is a regular file, special file or +directory, getfacl displays the owner, the group, and the +ACL. For directories getfacl displays additionally the +default ACL. With no options specified, getfacl displays +the filename, the owner, the group, and both the ACL and the default ACL, if +it exists. For more information on Cygwin and Windows ACLs, see +see in the Cygwin User's Guide. +The format for ACL output is as follows: + + # file: filename + # owner: name or uid + # group: name or uid + user::perm + user:name or uid:perm + group::perm + group:name or gid:perm + mask:perm + other:perm + default:user::perm + default:user:name or uid:perm + default:group::perm + default:group:name or gid:perm + default:mask:perm + default:other:perm + + + + kill Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...] - kill -l [signal] - -f, --force force, using win32 interface if necessary - -l, --list print a list of signal names - -s, --signal send signal (use kill --list for a list) - -h, --help output usage information and exit - -v, --version output version information and exit +kill -l [signal] +-f, --force force, using win32 interface if necessary +-l, --list print a list of signal names +-s, --signal send signal (use kill --list for a list) +-h, --help output usage information and exit +-v, --version output version information and exit The kill program allows you to send arbitrary @@ -188,17 +283,30 @@ also send program-specified signals such as SIGUSR1 to trigger actions within the program, like enabling debugging or re-opening log files. Each program defines the signals they understand. -Note that, unless you specific the -f option, -the "pid" values are the Cygwin pids, not the Windows pids. To get a -list of running programs and their Cygwin pids, use the Cygwin +You may need to specify the full path to use kill +from within some shells, including bash, the default Cygwin +shell. This is because bash defines a +kill builtin function; see the bash +man page under BUILTIN COMMANDS for more information. +To make sure you are using the Cygwin version, try + + +$ /bin/kill --version + + +which should give the Cygwin kill version number and +copyright information. + + +Unless you specific the -f option, the "pid" values +used by kill are the Cygwin pids, not the Windows pids. +To get a list of running programs and their Cygwin pids, use the Cygwin ps program. ps -W will display all windows pids. The kill -l option prints the name of the given signal, or a list of all signal names if no signal is given. -kill -h just displays the kill usage message. - To send a specific signal, use the -signN option, either with a signal number or a signal name (minus the "SIG" part), like these examples: @@ -238,10 +346,8 @@ SIGSTOP 17 sendable stop signal not from tty SIGTSTP 18 stop signal from tty SIGCONT 19 continue a stopped process SIGCHLD 20 to parent on child stop or exit -SIGCLD 20 System V name for SIGCHLD SIGTTIN 21 to readers pgrp upon background tty read SIGTTOU 22 like TTIN for output if (tp->t_local&LTOSTOP) -SIGIO 23 input/output possible signal SIGPOLL 23 System V name for SIGIO SIGXCPU 24 exceeded CPU time limit SIGXFSZ 25 exceeded file size limit @@ -815,51 +921,4 @@ print the message but does return the non-zero exit code. -dumper - - -Usage: dumper [OPTION] FILENAME WIN32PID -Dump core from WIN32PID to FILENAME.core - -d, --verbose be verbose while dumping - -h, --help output help information and exit - -q, --quiet be quiet while dumping (default) - -v, --version output version information and exit - - -The dumper utility can be used to create -core dump of running windows process. This core dump can be later loaded -to gdb an analyzed. One common way to use dumper is to -plug it into cygwin's Just-In-Time debugging facility by adding - - -error_start=x:\path\to\dumper.exe - - -to CYGWIN environment variable. Please note that -x:\path\to\dumper.exe is win32-style and not cygwin -path. If error_start is set this way, then dumper will -be started whenever some program encounters fatal error. - - - -dumper can be also be started from command line to create -core dump of any running process. Unfortunately, because of windows API -limitation, when core dump is created and dumper exits, -the target process is terminated too. - - - -To save the space in core dump, dumper doesn't write those -portions of target process' memory space that are loaded from executable and -dll files and are unchangeable, such as program code and debug info. Instead, -dumper saves paths to files which contain that data. When -core dump is loaded into gdb, it uses these paths to load appropriate files. -That means that if you create core dump on one machine and try to debug it on -other, you'll need to place identical copies of executable and dlls in the same -directories as on machine where core dump has been created. - - - - -