diff --git a/README.md b/README.md index f43ffbc..77d1f08 100644 --- a/README.md +++ b/README.md @@ -101,9 +101,42 @@ Try clang instead of gcc (fingers crossed). See [clang comparison](http://clang. #### How do I attach to a running process? -To be able to attach, the "attacher" needs to have special permissions. The -easiest method is to run a debug server as 'sudo' and connect to it. -See the question below. +To be able to attach a running process, the lldb process needs to have a +special capability to enable usage of the [*ptrace*] system call. [For security +reasons], this system call is restricted to the children processes of the +process doing the capture, which is the default way that `lldb` (or any debugger) works. + +But you can enable capturing of a running process by globally disabling scoping of +the ptrace system call: + +``` +sysctl -w kernel.yama.ptrace_scope=0 +``` + +But don't forget to set it back to `1` when you're done to keep your system safe. + +You'd have two other ways to attach to a running process, but because *lldb.vim* +uses python bindings and not the `lldb` executable, those can only work with `lldb-server`. +So please read [the following FAQ entry on how to run a remote server][remote-debug]. + +Instead of disabling `ptrace` scoping globally, you can as well disable it just for +the `lldb-server` executable: + +``` +sudo setcap cap_sys_ptrace=eip /usr/bin/lldb-server +``` + +To revert the setting: + +``` +sudo setcap -r /usr/bin/lldb-server +``` + +Another way would be to run `lldb-server` as root, as bypassing `ptrace` scoping is +amongst the root privileges. + +[*ptrace*]:https://en.wikipedia.org/wiki/Ptrace +[For security reasons]:http://askubuntu.com/a/153970/583565 #### Remote debugging does not work!! @@ -111,7 +144,7 @@ I haven't been able to get `gdbserver`, `lldb-gdbserver` or `lldb-server gdbserv to work properly with the python API. But the following works; run: ``` -# use sudo if you want to attach to a running process +# use sudo if you want to attach to a running process or setcap $ lldb-server platform --listen localhost:2345 # in older versions of lldb, use this instead @@ -128,3 +161,64 @@ on port 2345. Now, from the client (the plugin), run: ``` For more info on this, see [Remote Debugging](http://lldb.llvm.org/remote.html). + +#### How to debug an interactive commandline process? + +You'll need to make it possible to capture a remote process with `lldb`, see the above +two answers for more details. + +If you choose to disable globally `ptrace` scoping, you can run the following command +to open a new terminal buffer with your interactive command line program (once your +debugging session is started): + +``` viml +:1wincmd w | vsplit | term ./debugee -args | exec(":LL process attach -p " . b:terminal_job_pid) +``` + +Then you can setup breakpoints, watchpoints… and start the execution with `:LL continue`. +(don't forget to change `debugee` with your program name). + +If you prefer to use a debugging server instead, you can add the following viml function +in your `vimrc`: + +``` viml +function! LLSpawn(target, ...) + let port = a:0 >= 2 ? a:1 : 2345 + if !exists('g:lldb#remote_server') + if !system('pgrep "lldb-server"') + exe ":!lldb-server --listen " . host . ":" . port& + # or + # exe ":!sudo lldb-server --listen " . host . ":" . port& + sleep 1 + echomsg 'lldb-server started...' + else + echomsg 'lldb-server already running...' + endif + LL platform select remote-linux + exe "LL platform connect connect://" . host . ":" . port + let g:lldb#remote_server = 1 + endif + 1wincmd w + vsplit + exe ":term ". a:target + exe ":LL process attach -p " . b:terminal_job_pid + 2wincmd w +endfunction +``` + +then once your debugging session has been started, you can run: + +``` viml +call LLSpawn('./debuggee --args') " or +call LLSpawn('./debuggee --args', '4242') +``` + +which will start an `lldb-server` as suggested in the [former FAQ entry][remote-debug], +start the *debuggee* process and attach it, if no server is already runnning. If you choose to start the process as root, just +prefix the `lldb-server` call with `sudo`, otherwise you need to disable `ptrace` +scoping in any way suggested [above][attach-process]. + +[attach-process]:#how-do-I-attach-to-a-running-process +[remote-debug]:#remote-debugging-does-not-work + +