Mercurial > vim

comparison runtime/doc/channel.txt @ 17456:e414281d8bb4 v8.1.1726

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1726: the eval.txt help file is too big commit https://github.com/vim/vim/commit/ed997adaa1e9bd057ce732a73d933b739e9d0c30 Author: Bram Moolenaar <Bram@vim.org> Date: Sun Jul 21 16:42:00 2019 +0200 patch 8.1.1726: the eval.txt help file is too big Problem: The eval.txt help file is too big. Solution: Split off testing support to testing.txt. Move function details to where the functionality is explained.
author Bram Moolenaar <Bram@vim.org>
date Sun, 21 Jul 2019 16:45:05 +0200
parents c002c4899529
children 2704c4e3e20a
comparison
equal deleted inserted replaced
17455:4ae435e21326 17456:e414281d8bb4
1 *channel.txt* For Vim version 8.1. Last change: 2019 May 12 1 *channel.txt* For Vim version 8.1. Last change: 2019 Jul 21
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
16 3. Opening a channel |channel-open| 16 3. Opening a channel |channel-open|
17 4. Using a JSON or JS channel |channel-use| 17 4. Using a JSON or JS channel |channel-use|
18 5. Channel commands |channel-commands| 18 5. Channel commands |channel-commands|
19 6. Using a RAW or NL channel |channel-raw| 19 6. Using a RAW or NL channel |channel-raw|
20 7. More channel functions |channel-more| 20 7. More channel functions |channel-more|
21 8. Starting a job with a channel |job-start| 21 8. channel functions details |channel-functions-details|
22 9. Starting a job without a channel |job-start-nochannel| 22 9. Starting a job with a channel |job-start|
23 10. Job options |job-options| 23 10. Starting a job without a channel |job-start-nochannel|
24 11. Controlling a job |job-control| 24 11. Job functions |job-functions-details|
25 12. Using a prompt buffer |prompt-buffer| 25 12. Job options |job-options|
26 13. Controlling a job |job-control|
27 14. Using a prompt buffer |prompt-buffer|
26 28
27 {only when compiled with the |+channel| feature for channel stuff} 29 {only when compiled with the |+channel| feature for channel stuff}
28 You can check this with: `has('channel')` 30 You can check this with: `has('channel')`
29 {only when compiled with the |+job| feature for job stuff} 31 {only when compiled with the |+job| feature for job stuff}
30 You can check this with: `has('job')` 32 You can check this with: `has('job')`
458 For a NL channel this returns one message. 460 For a NL channel this returns one message.
459 For a JS or JSON channel this returns one decoded message. 461 For a JS or JSON channel this returns one decoded message.
460 This includes any sequence number. 462 This includes any sequence number.
461 463
462 ============================================================================== 464 ==============================================================================
463 8. Starting a job with a channel *job-start* *job* 465 8. channel functions details *channel-functions-details*
466
467 ch_canread({handle}) *ch_canread()*
468 Return non-zero when there is something to read from {handle}.
469 {handle} can be a Channel or a Job that has a Channel.
470
471 This is useful to read from a channel at a convenient time,
472 e.g. from a timer.
473
474 Note that messages are dropped when the channel does not have
475 a callback. Add a close callback to avoid that.
476
477
478 ch_close({handle}) *ch_close()*
479 Close {handle}. See |channel-close|.
480 {handle} can be a Channel or a Job that has a Channel.
481 A close callback is not invoked.
482
483
484 ch_close_in({handle}) *ch_close_in()*
485 Close the "in" part of {handle}. See |channel-close-in|.
486 {handle} can be a Channel or a Job that has a Channel.
487 A close callback is not invoked.
488
489
490 ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
491 Send {expr} over {handle}. The {expr} is encoded
492 according to the type of channel. The function cannot be used
493 with a raw channel. See |channel-use|.
494 {handle} can be a Channel or a Job that has a Channel.
495 *E917*
496 {options} must be a Dictionary. It must not have a "callback"
497 entry. It can have a "timeout" entry to specify the timeout
498 for this specific request.
499
500 ch_evalexpr() waits for a response and returns the decoded
501 expression. When there is an error or timeout it returns an
502 empty string.
503
504
505 ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
506 Send {string} over {handle}.
507 {handle} can be a Channel or a Job that has a Channel.
508
509 Works like |ch_evalexpr()|, but does not encode the request or
510 decode the response. The caller is responsible for the
511 correct contents. Also does not add a newline for a channel
512 in NL mode, the caller must do that. The NL in the response
513 is removed.
514 Note that Vim does not know when the text received on a raw
515 channel is complete, it may only return the first part and you
516 need to use |ch_readraw()| to fetch the rest.
517 See |channel-use|.
518
519
520 ch_getbufnr({handle}, {what}) *ch_getbufnr()*
521 Get the buffer number that {handle} is using for {what}.
522 {handle} can be a Channel or a Job that has a Channel.
523 {what} can be "err" for stderr, "out" for stdout or empty for
524 socket output.
525 Returns -1 when there is no buffer.
526
527
528 ch_getjob({channel}) *ch_getjob()*
529 Get the Job associated with {channel}.
530 If there is no job calling |job_status()| on the returned Job
531 will result in "fail".
532
533
534 ch_info({handle}) *ch_info()*
535 Returns a Dictionary with information about {handle}. The
536 items are:
537 "id" number of the channel
538 "status" "open", "buffered" or "closed", like
539 ch_status()
540 When opened with ch_open():
541 "hostname" the hostname of the address
542 "port" the port of the address
543 "sock_status" "open" or "closed"
544 "sock_mode" "NL", "RAW", "JSON" or "JS"
545 "sock_io" "socket"
546 "sock_timeout" timeout in msec
547 When opened with job_start():
548 "out_status" "open", "buffered" or "closed"
549 "out_mode" "NL", "RAW", "JSON" or "JS"
550 "out_io" "null", "pipe", "file" or "buffer"
551 "out_timeout" timeout in msec
552 "err_status" "open", "buffered" or "closed"
553 "err_mode" "NL", "RAW", "JSON" or "JS"
554 "err_io" "out", "null", "pipe", "file" or "buffer"
555 "err_timeout" timeout in msec
556 "in_status" "open" or "closed"
557 "in_mode" "NL", "RAW", "JSON" or "JS"
558 "in_io" "null", "pipe", "file" or "buffer"
559 "in_timeout" timeout in msec
560
561
562 ch_log({msg} [, {handle}]) *ch_log()*
563 Write {msg} in the channel log file, if it was opened with
564 |ch_logfile()|.
565 When {handle} is passed the channel number is used for the
566 message.
567 {handle} can be a Channel or a Job that has a Channel. The
568 Channel must be open for the channel number to be used.
569
570
571 ch_logfile({fname} [, {mode}]) *ch_logfile()*
572 Start logging channel activity to {fname}.
573 When {fname} is an empty string: stop logging.
574
575 When {mode} is omitted or "a" append to the file.
576 When {mode} is "w" start with an empty file.
577
578 Use |ch_log()| to write log messages. The file is flushed
579 after every message, on Unix you can use "tail -f" to see what
580 is going on in real time.
581
582 This function is not available in the |sandbox|.
583 NOTE: the channel communication is stored in the file, be
584 aware that this may contain confidential and privacy sensitive
585 information, e.g. a password you type in a terminal window.
586
587
588 ch_open({address} [, {options}]) *ch_open()*
589 Open a channel to {address}. See |channel|.
590 Returns a Channel. Use |ch_status()| to check for failure.
591
592 {address} has the form "hostname:port", e.g.,
593 "localhost:8765".
594
595 If {options} is given it must be a |Dictionary|.
596 See |channel-open-options|.
597
598
599 ch_read({handle} [, {options}]) *ch_read()*
600 Read from {handle} and return the received message.
601 {handle} can be a Channel or a Job that has a Channel.
602 For a NL channel this waits for a NL to arrive, except when
603 there is nothing more to read (channel was closed).
604 See |channel-more|.
605
606
607 ch_readblob({handle} [, {options}]) *ch_readblob()*
608 Like ch_read() but reads binary data and returns a |Blob|.
609 See |channel-more|.
610
611
612 ch_readraw({handle} [, {options}]) *ch_readraw()*
613 Like ch_read() but for a JS and JSON channel does not decode
614 the message. For a NL channel it does not block waiting for
615 the NL to arrive, but otherwise works like ch_read().
616 See |channel-more|.
617
618
619 ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
620 Send {expr} over {handle}. The {expr} is encoded
621 according to the type of channel. The function cannot be used
622 with a raw channel.
623 See |channel-use|. *E912*
624 {handle} can be a Channel or a Job that has a Channel.
625
626
627 ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
628 Send |String| or |Blob| {expr} over {handle}.
629 Works like |ch_sendexpr()|, but does not encode the request or
630 decode the response. The caller is responsible for the
631 correct contents. Also does not add a newline for a channel
632 in NL mode, the caller must do that. The NL in the response
633 is removed.
634 See |channel-use|.
635
636
637 ch_setoptions({handle}, {options}) *ch_setoptions()*
638 Set options on {handle}:
639 "callback" the channel callback
640 "timeout" default read timeout in msec
641 "mode" mode for the whole channel
642 See |ch_open()| for more explanation.
643 {handle} can be a Channel or a Job that has a Channel.
644
645 Note that changing the mode may cause queued messages to be
646 lost.
647
648 These options cannot be changed:
649 "waittime" only applies to |ch_open()|
650
651
652 ch_status({handle} [, {options}]) *ch_status()*
653 Return the status of {handle}:
654 "fail" failed to open the channel
655 "open" channel can be used
656 "buffered" channel can be read, not written to
657 "closed" channel can not be used
658 {handle} can be a Channel or a Job that has a Channel.
659 "buffered" is used when the channel was closed but there is
660 still data that can be obtained with |ch_read()|.
661
662 If {options} is given it can contain a "part" entry to specify
663 the part of the channel to return the status for: "out" or
664 "err". For example, to get the error status: >
665 ch_status(job, {"part": "err"})
666 <
667
668 ==============================================================================
669 9. Starting a job with a channel *job-start* *job*
464 670
465 To start a job and open a channel for stdin/stdout/stderr: > 671 To start a job and open a channel for stdin/stdout/stderr: >
466 let job = job_start(command, {options}) 672 let job = job_start(command, {options})
467 673
468 You can get the channel with: > 674 You can get the channel with: >
550 let job = job_start(command, {'close_cb': 'CloseHandler'}) 756 let job = job_start(command, {'close_cb': 'CloseHandler'})
551 757
552 You will want to do something more useful than "echomsg". 758 You will want to do something more useful than "echomsg".
553 759
554 ============================================================================== 760 ==============================================================================
555 9. Starting a job without a channel *job-start-nochannel* 761 10. Starting a job without a channel *job-start-nochannel*
556 762
557 To start another process without creating a channel: > 763 To start another process without creating a channel: >
558 let job = job_start(command, 764 let job = job_start(command,
559 \ {"in_io": "null", "out_io": "null", "err_io": "null"}) 765 \ {"in_io": "null", "out_io": "null", "err_io": "null"})
560 766
577 783
578 Note that the waittime for ch_open() gives the job one second to make the port 784 Note that the waittime for ch_open() gives the job one second to make the port
579 available. 785 available.
580 786
581 ============================================================================== 787 ==============================================================================
582 10. Job options *job-options* 788 11. Job functions *job-functions-details*
789
790 job_getchannel({job}) *job_getchannel()*
791 Get the channel handle that {job} is using.
792 To check if the job has no channel: >
793 if string(job_getchannel()) == 'channel fail'
794 <
795
796 job_info([{job}]) *job_info()*
797 Returns a Dictionary with information about {job}:
798 "status" what |job_status()| returns
799 "channel" what |job_getchannel()| returns
800 "cmd" List of command arguments used to start the job
801 "process" process ID
802 "tty_in" terminal input name, empty when none
803 "tty_out" terminal output name, empty when none
804 "exitval" only valid when "status" is "dead"
805 "exit_cb" function to be called on exit
806 "stoponexit" |job-stoponexit|
807
808 Only in Unix:
809 "termsig" the signal which terminated the process
810 (See |job_stop()| for the values)
811 only valid when "status" is "dead"
812
813 Only in MS-Windows:
814 "tty_type" Type of virtual console in use.
815 Values are "winpty" or "conpty".
816 See 'termwintype'.
817
818 Without any arguments, returns a List with all Job objects.
819
820
821 job_setoptions({job}, {options}) *job_setoptions()*
822 Change options for {job}. Supported are:
823 "stoponexit" |job-stoponexit|
824 "exit_cb" |job-exit_cb|
825
826
827 job_start({command} [, {options}]) *job_start()*
828 Start a job and return a Job object. Unlike |system()| and
829 |:!cmd| this does not wait for the job to finish.
830 To start a job in a terminal window see |term_start()|.
831
832 If the job fails to start then |job_status()| on the returned
833 Job object results in "fail" and none of the callbacks will be
834 invoked.
835
836 {command} can be a String. This works best on MS-Windows. On
837 Unix it is split up in white-separated parts to be passed to
838 execvp(). Arguments in double quotes can contain white space.
839
840 {command} can be a List, where the first item is the executable
841 and further items are the arguments. All items are converted
842 to String. This works best on Unix.
843
844 On MS-Windows, job_start() makes a GUI application hidden. If
845 want to show it, Use |:!start| instead.
846
847 The command is executed directly, not through a shell, the
848 'shell' option is not used. To use the shell: >
849 let job = job_start(["/bin/sh", "-c", "echo hello"])
850 < Or: >
851 let job = job_start('/bin/sh -c "echo hello"')
852 < Note that this will start two processes, the shell and the
853 command it executes. If you don't want this use the "exec"
854 shell command.
855
856 On Unix $PATH is used to search for the executable only when
857 the command does not contain a slash.
858
859 The job will use the same terminal as Vim. If it reads from
860 stdin the job and Vim will be fighting over input, that
861 doesn't work. Redirect stdin and stdout to avoid problems: >
862 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
863 <
864 The returned Job object can be used to get the status with
865 |job_status()| and stop the job with |job_stop()|.
866
867 Note that the job object will be deleted if there are no
868 references to it. This closes the stdin and stderr, which may
869 cause the job to fail with an error. To avoid this keep a
870 reference to the job. Thus instead of: >
871 call job_start('my-command')
872 < use: >
873 let myjob = job_start('my-command')
874 < and unlet "myjob" once the job is not needed or is past the
875 point where it would fail (e.g. when it prints a message on
876 startup). Keep in mind that variables local to a function
877 will cease to exist if the function returns. Use a
878 script-local variable if needed: >
879 let s:myjob = job_start('my-command')
880 <
881 {options} must be a Dictionary. It can contain many optional
882 items, see |job-options|.
883
884
885 job_status({job}) *job_status()* *E916*
886 Returns a String with the status of {job}:
887 "run" job is running
888 "fail" job failed to start
889 "dead" job died or was stopped after running
890
891 On Unix a non-existing command results in "dead" instead of
892 "fail", because a fork happens before the failure can be
893 detected.
894
895 If an exit callback was set with the "exit_cb" option and the
896 job is now detected to be "dead" the callback will be invoked.
897
898 For more information see |job_info()|.
899
900
901 job_stop({job} [, {how}]) *job_stop()*
902 Stop the {job}. This can also be used to signal the job.
903
904 When {how} is omitted or is "term" the job will be terminated.
905 For Unix SIGTERM is sent. On MS-Windows the job will be
906 terminated forcedly (there is no "gentle" way).
907 This goes to the process group, thus children may also be
908 affected.
909
910 Effect for Unix:
911 "term" SIGTERM (default)
912 "hup" SIGHUP
913 "quit" SIGQUIT
914 "int" SIGINT
915 "kill" SIGKILL (strongest way to stop)
916 number signal with that number
917
918 Effect for MS-Windows:
919 "term" terminate process forcedly (default)
920 "hup" CTRL_BREAK
921 "quit" CTRL_BREAK
922 "int" CTRL_C
923 "kill" terminate process forcedly
924 Others CTRL_BREAK
925
926 On Unix the signal is sent to the process group. This means
927 that when the job is "sh -c command" it affects both the shell
928 and the command.
929
930 The result is a Number: 1 if the operation could be executed,
931 0 if "how" is not supported on the system.
932 Note that even when the operation was executed, whether the
933 job was actually stopped needs to be checked with
934 |job_status()|.
935
936 If the status of the job is "dead", the signal will not be
937 sent. This is to avoid to stop the wrong job (esp. on Unix,
938 where process numbers are recycled).
939
940 When using "kill" Vim will assume the job will die and close
941 the channel.
942
943
944 ==============================================================================
945 12. Job options *job-options*
583 946
584 The {options} argument in job_start() is a dictionary. All entries are 947 The {options} argument in job_start() is a dictionary. All entries are
585 optional. Some options can be used after the job has started, using 948 optional. Some options can be used after the job has started, using
586 job_setoptions(job, {options}). Many options can be used with the channel 949 job_setoptions(job, {options}). Many options can be used with the channel
587 related to the job, using ch_setoptions(channel, {options}). 950 related to the job, using ch_setoptions(channel, {options}).
771 accessible for others). Use |setfperm()| to change this. 1134 accessible for others). Use |setfperm()| to change this.
772 1135
773 If the file already exists it is truncated. 1136 If the file already exists it is truncated.
774 1137
775 ============================================================================== 1138 ==============================================================================
776 11. Controlling a job *job-control* 1139 13. Controlling a job *job-control*
777 1140
778 To get the status of a job: > 1141 To get the status of a job: >
779 echo job_status(job) 1142 echo job_status(job)
780 1143
781 To make a job stop running: > 1144 To make a job stop running: >
787 job_stop(job, "kill") 1150 job_stop(job, "kill")
788 1151
789 For more options see |job_stop()|. 1152 For more options see |job_stop()|.
790 1153
791 ============================================================================== 1154 ==============================================================================
792 12. Using a prompt buffer *prompt-buffer* 1155 14. Using a prompt buffer *prompt-buffer*
793 1156
794 If you want to type input for the job in a Vim window you have a few options: 1157 If you want to type input for the job in a Vim window you have a few options:
795 - Use a normal buffer and handle all possible commands yourself. 1158 - Use a normal buffer and handle all possible commands yourself.
796 This will be complicated, since there are so many possible commands. 1159 This will be complicated, since there are so many possible commands.
797 - Use a terminal window. This works well if what you type goes directly to 1160 - Use a terminal window. This works well if what you type goes directly to