Mercurial > emacs
comparison doc/lispref/os.texi @ 103049:952d96227f27
* os.texi (Command-Line Arguments): Document
command-line-args-left.
(Suspending Emacs): Adapt text to multi-tty case. Document use of
terminal objects for tty arguments.
(Startup Summary): Add xref to Session Management.
(Session Management): Mention emacs-session-restore. Copyedits.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Wed, 22 Apr 2009 04:21:39 +0000 |
parents | 91ec7dabacb2 |
children | b269cabac20c |
comparison
equal
deleted
inserted
replaced
103048:b5e8a934cfd1 | 103049:952d96227f27 |
---|---|
187 @samp{--no-splash} or @samp{-Q} command-line options were specified. | 187 @samp{--no-splash} or @samp{-Q} command-line options were specified. |
188 | 188 |
189 @item | 189 @item |
190 If started by the X session manager, it calls | 190 If started by the X session manager, it calls |
191 @code{emacs-session-restore} passing it as argument the ID of the | 191 @code{emacs-session-restore} passing it as argument the ID of the |
192 previous session. @c FIXME: add an xref to the Emacs manual! | 192 previous session. @xref{Session Management}. |
193 @end enumerate | 193 @end enumerate |
194 | 194 |
195 @defopt inhibit-startup-screen | 195 @defopt inhibit-startup-screen |
196 This variable, if non-@code{nil}, inhibits the startup screen. In | 196 This variable, if non-@code{nil}, inhibits the startup screen. In |
197 that case, Emacs typically displays the @samp{*scratch*} buffer; but | 197 that case, Emacs typically displays the @samp{*scratch*} buffer; but |
486 @defvar command-line-args | 486 @defvar command-line-args |
487 The value of this variable is the list of command-line arguments passed | 487 The value of this variable is the list of command-line arguments passed |
488 to Emacs. | 488 to Emacs. |
489 @end defvar | 489 @end defvar |
490 | 490 |
491 @defvar command-line-args-left | |
492 The value of this variable is the list of command-line arguments that | |
493 have not yet been processed. @code{argv} is an alias for this. | |
494 @end defvar | |
495 | |
491 @defvar command-line-functions | 496 @defvar command-line-functions |
492 This variable's value is a list of functions for handling an | 497 This variable's value is a list of functions for handling an |
493 unrecognized command-line argument. Each time the next argument to be | 498 unrecognized command-line argument. Each time the next argument to be |
494 processed has no special meaning, the functions in this list are called, | 499 processed has no special meaning, the functions in this list are called, |
495 in order of appearance, until one of them returns a non-@code{nil} | 500 in order of appearance, until one of them returns a non-@code{nil} |
580 | 585 |
581 @node Suspending Emacs | 586 @node Suspending Emacs |
582 @subsection Suspending Emacs | 587 @subsection Suspending Emacs |
583 @cindex suspending Emacs | 588 @cindex suspending Emacs |
584 | 589 |
585 @dfn{Suspending Emacs} means stopping Emacs temporarily and returning | 590 On text-only terminals, it is possible to @dfn{suspend Emacs}, which |
586 control to its superior process, which is usually the shell. This | 591 means stopping Emacs temporarily and returning control to its superior |
587 allows you to resume editing later in the same Emacs process, with the | 592 process, which is usually the shell. This allows you to resume |
588 same buffers, the same kill ring, the same undo history, and so on. To | 593 editing later in the same Emacs process, with the same buffers, the |
589 resume Emacs, use the appropriate command in the parent shell---most | 594 same kill ring, the same undo history, and so on. To resume Emacs, |
590 likely @code{fg}. | 595 use the appropriate command in the parent shell---most likely |
596 @code{fg}. | |
591 | 597 |
592 @cindex controlling terminal | 598 @cindex controlling terminal |
593 Suspending works only on a terminal device from which the Emacs | 599 Suspending works only on a terminal device from which the Emacs |
594 session was started. We call that device the @dfn{controlling | 600 session was started. We call that device the @dfn{controlling |
595 terminal} of the session. | 601 terminal} of the session. Suspending is not allowed if the |
602 controlling terminal is a graphical terminal. | |
596 | 603 |
597 Some operating systems do not support suspension of jobs; on these | 604 Some operating systems do not support suspension of jobs; on these |
598 systems, ``suspension'' actually creates a new shell temporarily as a | 605 systems, ``suspension'' actually creates a new shell temporarily as a |
599 subprocess of Emacs. Then you would exit the shell to return to Emacs. | 606 subprocess of Emacs. Then you would exit the shell to return to Emacs. |
600 | |
601 Suspension is not useful with window systems, because the Emacs job | |
602 may not have a parent that can resume it again, and in any case you can | |
603 give input to some other job such as a shell merely by moving to a | |
604 different window. Therefore, suspending is not allowed when Emacs is using | |
605 a window system (X, MS Windows). | |
606 | 607 |
607 @defun suspend-emacs &optional string | 608 @defun suspend-emacs &optional string |
608 This function stops Emacs and returns control to the superior process. | 609 This function stops Emacs and returns control to the superior process. |
609 If and when the superior process resumes Emacs, @code{suspend-emacs} | 610 If and when the superior process resumes Emacs, @code{suspend-emacs} |
610 returns @code{nil} to its caller in Lisp. | 611 returns @code{nil} to its caller in Lisp. |
611 | 612 |
612 This function works only on the controlling terminal of the Emacs | 613 This function works only on the controlling terminal of the Emacs |
613 session; to relinquish control of other tty devices, use | 614 session; to relinquish control of other tty devices, use |
614 @code{suspend-tty} (see below). If the Emacs session uses more than | 615 @code{suspend-tty} (see below). If the Emacs session uses more than |
615 one terminal device, you will need to delete the frames on all the | 616 one terminal, you must delete the frames on all the other terminals |
616 other devices before suspending Emacs, otherwise this function signals | 617 before suspending Emacs, or this function signals an error. |
617 an error. | 618 @xref{Multiple Terminals}. |
618 | 619 |
619 If @var{string} is non-@code{nil}, its characters are sent to be read | 620 If @var{string} is non-@code{nil}, its characters are sent to Emacs's |
620 as terminal input by Emacs's superior shell. The characters in | 621 superior shell, to be read as terminal input. The characters in |
621 @var{string} are not echoed by the superior shell; only the results | 622 @var{string} are not echoed by the superior shell; only the results |
622 appear. | 623 appear. |
623 | 624 |
624 Before suspending, @code{suspend-emacs} runs the normal hook | 625 Before suspending, @code{suspend-emacs} runs the normal hook |
625 @code{suspend-hook}. | 626 @code{suspend-hook}. After the user resumes Emacs, |
626 | 627 @code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}. |
627 After the user resumes Emacs, @code{suspend-emacs} runs the normal hook | 628 @xref{Hooks}. |
628 @code{suspend-resume-hook}. @xref{Hooks}. | |
629 | 629 |
630 The next redisplay after resumption will redraw the entire screen, | 630 The next redisplay after resumption will redraw the entire screen, |
631 unless the variable @code{no-redraw-on-reenter} is non-@code{nil} | 631 unless the variable @code{no-redraw-on-reenter} is non-@code{nil}. |
632 (@pxref{Refresh Screen}). | 632 @xref{Refresh Screen}. |
633 | 633 |
634 In the following example, note that @samp{pwd} is not echoed after | 634 In the following example, note that @samp{pwd} is not echoed after |
635 Emacs is suspended. But it is read and executed by the shell. | 635 Emacs is suspended. But it is read and executed by the shell. |
636 | 636 |
637 @smallexample | 637 @smallexample |
689 | 689 |
690 @defun suspend-tty &optional tty | 690 @defun suspend-tty &optional tty |
691 If @var{tty} specifies a terminal device used by Emacs, this function | 691 If @var{tty} specifies a terminal device used by Emacs, this function |
692 relinquishes the device and restores it to its prior state. Frames | 692 relinquishes the device and restores it to its prior state. Frames |
693 that used the device continue to exist, but are not updated and Emacs | 693 that used the device continue to exist, but are not updated and Emacs |
694 doesn't read input from them. If @var{tty} is a frame, it means that | 694 doesn't read input from them. @var{tty} can be a terminal object, a |
695 frame's terminal; if it is @code{nil}, the function uses the selected | 695 frame (meaning the terminal for that frame), or @code{nil} (meaning |
696 frame's terminal. If @var{tty} is already suspended, the function | 696 the terminal for the selected frame). @xref{Multiple Terminals}. |
697 does nothing. | 697 |
698 | 698 If @var{tty} is already suspended, this function does nothing. |
699 This function runs the hook @code{suspend-tty-functions} (each | 699 |
700 function gets one argument, the terminal that corresponds to | 700 This function runs the hook @code{suspend-tty-functions}, passing the |
701 @var{tty}). | 701 terminal object as an argument to each function. |
702 @end defun | 702 @end defun |
703 | 703 |
704 @defun resume-tty &optional tty | 704 @defun resume-tty &optional tty |
705 Resume the previously suspended terminal device @var{tty}. If | 705 This function resumes the previously suspended terminal device |
706 @var{tty} is a frame, it means resume that frame's terminal; | 706 @var{tty}; @var{tty} can be a terminal object, a frame (meaning the |
707 @code{nil} means the selected frame. | 707 terminal for that frame), or @code{nil} (meaning the terminal for the |
708 selected frame). | |
708 | 709 |
709 This function reopens the terminal device, re-initializes it, and | 710 This function reopens the terminal device, re-initializes it, and |
710 redraws its with that terminal's selected frame. It then runs the | 711 redraws its with that terminal's selected frame. It then runs the |
711 hook @code{resume-tty-functions}, passing each function the terminal | 712 hook @code{resume-tty-functions}, passing the terminal object as an |
712 which corresponds to @var{tty}. | 713 argument to each function. |
713 | 714 |
714 If the same device is already used by another Emacs terminal, this | 715 If the same device is already used by another Emacs terminal, this |
715 function signals an error. | 716 function signals an error. |
716 @end defun | 717 @end defun |
717 | 718 |
718 @defun controlling-tty-p &optional terminal | 719 @defun controlling-tty-p &optional terminal |
719 This function returns non-@code{nil} if @var{terminal} is the | 720 This function returns non-@code{nil} if @var{terminal} is the |
720 controlling terminal device of the Emacs session. | 721 controlling terminal of the Emacs session; @code{terminal} can be a |
722 terminal object, a frame (meaning the terminal for that frame), or | |
723 @code{nil} (meaning the terminal for the selected frame). | |
721 @end defun | 724 @end defun |
722 | 725 |
723 @deffn Command suspend-frame | 726 @deffn Command suspend-frame |
724 This command @dfn{suspends} a frame. For GUI frames, it calls | 727 This command @dfn{suspends} a frame. For GUI frames, it calls |
725 @code{iconify-frame} (@pxref{Visibility of Frames}); for text-only | 728 @code{iconify-frame} (@pxref{Visibility of Frames}); for text-only |
2129 | 2132 |
2130 @node Session Management | 2133 @node Session Management |
2131 @section Session Management | 2134 @section Session Management |
2132 @cindex session manager | 2135 @cindex session manager |
2133 | 2136 |
2134 Emacs supports the X Session Management Protocol for suspension and | 2137 Emacs supports the X Session Management Protocol, which is used to |
2135 restart of applications. In the X Window System, a program called the | 2138 suspend and restart applications. In the X Window System, a program |
2136 @dfn{session manager} has the responsibility to keep track of the | 2139 called the @dfn{session manager} is responsible for keeping track of |
2137 applications that are running. During shutdown, the session manager | 2140 the applications that are running. When the X server shuts down, the |
2138 asks applications to save their state, and delays the actual shutdown | 2141 session manager asks applications to save their state, and delays the |
2139 until they respond. An application can also cancel the shutdown. | 2142 actual shutdown until they respond. An application can also cancel |
2143 the shutdown. | |
2140 | 2144 |
2141 When the session manager restarts a suspended session, it directs | 2145 When the session manager restarts a suspended session, it directs |
2142 these applications to individually reload their saved state. It does | 2146 these applications to individually reload their saved state. It does |
2143 this by specifying a special command-line argument that says what | 2147 this by specifying a special command-line argument that says what |
2144 saved session to restore. For Emacs, this argument is @samp{--smid | 2148 saved session to restore. For Emacs, this argument is @samp{--smid |
2145 @var{session}}. | 2149 @var{session}}. |
2146 | 2150 |
2147 @defvar emacs-save-session-functions | 2151 @defvar emacs-save-session-functions |
2148 Emacs supports saving state by using a hook called | 2152 Emacs supports saving state via a hook called |
2149 @code{emacs-save-session-functions}. Each function in this hook is | 2153 @code{emacs-save-session-functions}. Emacs runs this hook when the |
2150 called when the session manager tells Emacs that the window system is | 2154 session manager tells it that the window system is shutting down. The |
2151 shutting down. The functions are called with no arguments and with the | 2155 functions are called with no arguments, and with the current buffer |
2152 current buffer set to a temporary buffer. Each function can use | 2156 set to a temporary buffer. Each function can use @code{insert} to add |
2153 @code{insert} to add Lisp code to this buffer. At the end, Emacs | 2157 Lisp code to this buffer. At the end, Emacs saves the buffer in a |
2154 saves the buffer in a file that a subsequent Emacs invocation will | 2158 file, called the @dfn{session file}. |
2155 load in order to restart the saved session. | 2159 |
2160 @findex emacs-session-restore | |
2161 Subsequently, when the session manager restarts Emacs, it loads the | |
2162 session file automatically (@pxref{Loading}). This is performed by a | |
2163 function named @code{emacs-session-restore}, which is called during | |
2164 startup. @xref{Startup Summary}. | |
2156 | 2165 |
2157 If a function in @code{emacs-save-session-functions} returns | 2166 If a function in @code{emacs-save-session-functions} returns |
2158 non-@code{nil}, Emacs tells the session manager to cancel the | 2167 non-@code{nil}, Emacs tells the session manager to cancel the |
2159 shutdown. | 2168 shutdown. |
2160 @end defvar | 2169 @end defvar |