Merge pull request #2266 from h-east/update-remote

Update remote.{txt,jax}

Author: h-east

doc/remote.jax

@@ -1,4 +1,4 @@
-*remote.txt*    For Vim バージョン 9.1.  Last change: 2022 Feb 17
+*remote.txt*    For Vim バージョン 9.1.  Last change: 2025 Aug 22
 
 
 		VIMリファレンスマニュアル    by Bram Moolenaar
@@ -9,6 +9,7 @@ Vimクライアントサーバー通信				*client-server*
 1. 共通機能			|clientserver|
 2. X11特有の項目		|x11-clientserver|
 3. Win32特有の項目		|w32-clientserver|
+4. ソケットサーバー固有の項目	|socketserver-clientserver|
 
 ==============================================================================
 1. 共通機能						*clientserver*
@@ -62,7 +63,9 @@ Vimクライアントサーバー通信				*client-server*
    --servername {name}		サーバー名{name}になる。--remote コマンドのど
 				れか1つと併用すると、デフォルトのサーバーでは
 				なく{name}で指定されるサーバーに接続する(下を
-				参照)。使用される名前は大文字になる。
+				参照)。使用される名前は大文字になる。ソケット
+				サーバーを使用する場合は、パスを指定できる。詳
+				細については |socketserver-name| を参照。
 								*--remote-send*
    --remote-send {keys}		サーバーに{keys}を送信して終了する。{keys} に
 				マップは適用されない。特殊キー名が使用できる。
@@ -72,6 +75,12 @@ Vimクライアントサーバー通信				*client-server*
 				出力に印刷する。
 								*--serverlist*
    --serverlist			サーバー名のリストを表示する。
+								*--clientserver*
+   --clientserver {method}	指定されたメソッド {method} をクライアントサー
+				バー機能のバックエンドとして使用する。"socket"
+				または "x11" のいずれかを指定できる。
+				{Vim が |+X11| と |+socketserver| の両方の機能
+				付きでコンパイルされたときのみ有効}
 
 
 使用例 ~
@@ -103,7 +112,8 @@ Vimクライアントサーバー通信				*client-server*
 は、利用できる名前になるように後置名が付加される。例えば、1つのX-Serverで2つ目
 のgvimを起動したときには "gvim1" というようになる。その時のサーバー名へは組み
 込み変数|v:servername|によりアクセスできる。サーバー名の大文字小文字は区別され
-ないので、"gvim" と "GVIM" は同じとみなされる。
+ないので、"gvim" と "GVIM" は同じとみなされる。Note ソケットサーバーが使用され
+ている場合、いくつかの違いがあることに注意。|socketserver-differences| を参照。
 
 Vimが引数 --remote や --remote-wait または --remote-send で起動された時には、
 上記のようにその名前で起動されたサーバーを探そうと試みる。正確に一致するサー
@@ -117,7 +127,8 @@ Vimが引数 --remote や --remote-wait または --remote-send で起動され
 かを知る必要は無い。
 
 引数 --serverlist はVimに登録(実行)されている全てのコマンドサーバーを、標準出
-力(stdout)に印刷して終了する。
+力(stdout)に印刷して終了する。ソケットサーバーが使用されている場合は注意点があ
+る。|socketserver-differences| を参照。
 
 							*{server}*
 引数 {server} はいくつかの関数で使われる。これが空文字列の場合、Unix ではデフォ
@@ -200,4 +211,64 @@ gvimを使っている時には、--remote-wait は以下のようにしない
 
 	start /w gvim --remote-wait file.txt
 <
+==============================================================================
+4. ソケットサーバー固有の項目			    *socketserver-clientserver*
+				    *E1563* *E1564* *E1565* *E1566* *E1567*
+
+クライアントとサーバー間の通信は Unix ドメインソケットを使用して行われる。これ
+らのソケットは、以下の利用可能な順序で以下のディレクトリに配置される。
+    1. 環境に $XDG_RUNTIME_DIR が設定されている場合は "$XDG_RUTIME_DIR/vim"。
+    2. "$TMPDIR/vim-[uid]"。ここで "[uid]" はユーザーの uid である。このディレ
+       クトリのアクセス権限は 700 に設定され、ユーザーのみが読み書きできる。
+       $TMPDIR が設定されていない場合は、"/tmp" が使用される。
+
+						    *socketserver-name*
+サーバー id/名前を指定する際は、汎用名、絶対パス、または相対パスで指定できる。
+サーバー id が "/" (絶対パス) または "./" または "../" (相対パス) で始まる場
+合、ソケットへのパスとして扱われる。それ以外の場合、サーバー id は上記の共通
+ディレクトリに配置されるソケットのファイル名になる。Note サーバー id/名前をパ
+スとして指定する場合、スラッシュ "/" のみを含めることができる。"abc/dir" のよ
+うな名前は無効である。
+
+ソケットサーバー機能は、GTK GUI 版とターミナル版の両方の Vim で使用できる。Vim
+が |+autoservername| 機能付きでコンパイルされていない場合、GUI 版であっても
+X11 と同様にソケットサーバーを明示的に起動する必要がある。
+
+Vim がクラッシュしたり、正常に終了しなかったりした場合、ソケットサーバーはソ
+ケットファイルを削除せずそのまま残す。これは通常問題にはならない。ソケット名が
+既に使用されている場合、Vim はそのソケットがデッド (どのプロセスにも接続されて
+いない) かどうかを確認し、新しい名前を探す代わりに既存のソケットを置き換えるこ
+とができるためである。
+
+別のアプリケーションから Vim ソケットサーバーにコマンドを送信するには、ソース
+ファイル src/os_unix.c を読むこと。そこには、使用されるプロトコルの詳細な説明
+があります。
+
+						    *socketserver-differences*
+機能の大部分は X11 と同じたが、X11 ではクライアントがサーバーとして動作してい
+なくてもサーバーと通信できるのに対し、ソケットサーバーではクライアントであって
+もサーバーが動作している必要がある。ただし、|serverlist()| または
+|--serverlist| 引数は例外で、サーバーが動作している必要はない。
+
+さらに、サーバー id またはクライアント id は、X11 や MS-Windows のような数値
+(16進数で表示) ではなく、ソケットへの絶対パスになる。これは |v:servername| 変
+数で確認できる。
+
+|--serverlist| 引数は X11 と同様に動作するが、確認対象は上記で挙げた共通ディレ
+クトリに限られる。したがって、ソケットにカスタムのパスを使用している場合は検出
+されない。例えば、|--serverlist| を実行している Vim プロセスの
+$XDG_RUNTIME_DIR 以外、あるいは <$TMPDIR または /tmp> /vim 以外の場所にあるパ
+スは検出対象にならない。
+
+|+socketserver| と |+X11| の両方をコンパイルしている場合、使用可能なサーバーの
+一覧を表示するには、|--clientserver| を "socket" に設定し、|--serverlist| と組
+み合わせて追加する必要がある。1 つのコマンドで両方の種類のバックエンドの一覧を
+表示することはできない。
+
+						    *socketserver-x11*
+Vim が |+X11| と |+socketserver| の両方でコンパイルされている場合、どちらのバッ
+クエンドを使用するかは起動時に |--clientserver| 引数によって決定される。指定さ
+れていない場合はデフォルトで X11 が使用される。ソケットサーバーを使用する Vim
+インスタンスは、X11 を使用する Vim インスタンスと通信できない。
+
  vim:tw=78:sw=4:ts=8:noet:ft=help:norl:

en/remote.txt

@@ -1,4 +1,4 @@
-*remote.txt*    For Vim version 9.1.  Last change: 2022 Feb 17
+*remote.txt*    For Vim version 9.1.  Last change: 2025 Aug 22
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -9,6 +9,7 @@ Vim client-server communication				*client-server*
 1. Common functionality		|clientserver|
 2. X11 specific items		|x11-clientserver|
 3. MS-Windows specific items	|w32-clientserver|
+4. Socket server specific items	|socketserver-clientserver|
 
 ==============================================================================
 1. Common functionality					*clientserver*
@@ -61,7 +62,10 @@ The following command line arguments are available:
    --servername {name}		Become the server {name}.  When used together
 				with one of the --remote commands: connect to
 				server {name} instead of the default (see
-				below).  The name used will be uppercase.
+				below).  The name used will be uppercase.  If
+				using the socketserver, you can specify a
+				path, see |socketserver-name| for more
+				details.
 								*--remote-send*
    --remote-send {keys}		Send {keys} to server and exit.  The {keys}
 				are not mapped.  Special key names are
@@ -72,6 +76,12 @@ The following command line arguments are available:
 				on stdout.
 								*--serverlist*
    --serverlist			Output a list of server names.
+								*--clientserver*
+   --clientserver {method}	Use the specified method {method} as the
+				backend for clientserver functionality.  Can
+				either be "socket" or "x11".
+				{only available when compiled with both |+X11|
+				and |+socketserver| features}
 
 
 Examples ~
@@ -105,7 +115,8 @@ specified name is not available, a postfix is applied until a free name is
 encountered, i.e. "gvim1" for the second invocation of gvim on a particular
 X-server.  The resulting name is available in the servername builtin variable
 |v:servername|.  The case of the server name is ignored, thus "gvim" and
-"GVIM" are considered equal.
+"GVIM" are considered equal.  Note if a socket server is being used, there are
+some differences, see |socketserver-differences|.
 
 When Vim is invoked with --remote, --remote-wait or --remote-send it will try
 to locate the server name determined by the invocation name and --servername
@@ -119,7 +130,8 @@ itself.  This way it is not necessary to know whether gvim is already started
 when sending command to it.
 
 The --serverlist argument will cause Vim to print a list of registered command
-servers on the standard output (stdout) and exit.
+servers on the standard output (stdout) and exit.  If a socket server is being
+used, there are caveats, see |socketserver-differences|.
 							*{server}*
 The {server} argument is used by several functions.  When this is an empty
 string then on Unix the default server name is used, which is "GVIM".  On
@@ -206,4 +218,64 @@ When using gvim, the --remote-wait only works properly this way: >
 
 	start /w gvim --remote-wait file.txt
 <
+==============================================================================
+4. Socket server specific items			    *socketserver-clientserver*
+				    *E1563* *E1564* *E1565* *E1566* *E1567*
+
+The communication between client and server is done using Unix domain sockets.
+These sockets are either placed in these directories in the following order of
+availability:
+    1. "$XDG_RUTIME_DIR/vim" if $XDG_RUNTIME_DIR is set in the environment.
+    2. "$TMPDIR/vim-[uid]", where "[uid]" is the uid of the user.  This
+       directory will have the access permissions set to 700 so only the user
+       can read or write from/to it.  If $TMPDIR is not set, "/tmp" is used.
+
+						    *socketserver-name*
+When specifying the server id/name, it can be taken as a generic name or an
+absolute or relative path.  If the server id starts with either a "/"
+(absolute) or "./" | "../" (relative), then it is taken as path to the socket.
+Otherwise the server id will be the filename of the socket which will be
+placed in the above common directories.  Note that a server id/name can only
+contain slashes "/" if it is taken as a path, so names such as "abc/dir" will
+be invalid.
+
+Socket server functionality is available in both GTK GUI and terminal versions
+of Vim.  Unless Vim is compiled with |+autoservername| feature, the socket
+server will have to started explicitly, just like X11, even in the GUI.
+
+If Vim crashes or does not exit cleanly, the socket server will not remove the
+socket file and it will be left around.  This is generally not a problem,
+because if a socket name is taken, Vim checks if the socket in its place is
+dead (not attached to any process), and can replace it instead of finding a
+new name.
+
+To send commands to a Vim socket server from another application, read the
+source file src/os_unix.c, there is detailed description of the protocol used.
+
+						    *socketserver-differences*
+Most of the functionality is the same as X11, however unlike X11, where the
+client does not need to be a server in order to communicate with another
+server, the socket server requires the server to be running even as a client.
+The exception is |serverlist()| or the |--serverlist| argument, which does not
+require the server to be running.
+
+Additionally, the server id or client id will not be a number like X11 or
+MS-Windows (shown in hex representation), instead it is the absolute path to
+the socket.  This can be seen via the |v:servername| variable.
+
+The |--serverlist| argument will act just like X11, however it only checks the
+given common directories above.  If a custom path is used for a socket, it
+will not be detected, such as a path either not in $XDG_RUNTIME_DIR or
+<$TMPDIR or /tmp>/vim of the |--serverlist| Vim process.
+
+If you have both |+socketserver| and |+X11| compiled, you will need to add
+|--clientserver| set to "socket" in combination with |--serverlist| to list
+the available servers.  You cannot list both types of backends in one command.
+
+						    *socketserver-x11*
+If Vim is compiled with both |+X11| and |+socketserver|, then deciding which
+backend to use is done at startup time, via the |--clientserver| argument.  By
+default if it is not specified, then X11 will be used.  A Vim instance using a
+socket server cannot communicate with one using X11.
+
  vim:tw=78:sw=4:ts=8:noet:ft=help:norl: