diff options
Diffstat (limited to 'doc/lispref/os.texi')
| -rw-r--r-- | doc/lispref/os.texi | 138 |
1 files changed, 134 insertions, 4 deletions
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index c8c64ddde89..3ba3da459bf 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -972,6 +972,9 @@ Hewlett-Packard HPUX operating system. @item nacl Google Native Client (@acronym{NaCl}) sandboxing system. +@item android +The Open Handset Alliance's Android operating system. + @item ms-dos Microsoft's DOS@. Emacs compiled with DJGPP for MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on MS-Windows. @@ -1279,13 +1282,33 @@ This function returns the real @acronym{UID} of the user. This function returns the effective @acronym{UID} of the user. @end defun +@defun file-user-uid +This function returns the connection-local value for the user's +effective @acronym{UID}. If @code{default-directory} is local, this +is equivalent to @code{user-uid}, but for remote files (@pxref{Remote +Files, , , emacs, The GNU Emacs Manual}), it will return the +@acronym{UID} for the user associated with that remote connection; if +the remote connection has no associated user, it will instead return +-1. +@end defun + @cindex GID +@defun group-real-gid +This function returns the real @acronym{GID} of the Emacs process. +@end defun + @defun group-gid This function returns the effective @acronym{GID} of the Emacs process. @end defun -@defun group-real-gid -This function returns the real @acronym{GID} of the Emacs process. +@defun file-group-gid +This function returns the connection-local value for the user's +effective @acronym{GID}. Similar to @code{file-user-uid}, if +@code{default-directory} is local, this is equivalent to +@code{group-gid}, but for remote files (@pxref{Remote Files, , , +emacs, The GNU Emacs Manual}), it will return the @acronym{GID} for +the user associated with that remote connection; if the remote +connection has no associated user, it will instead return -1. @end defun @defun system-users @@ -2852,7 +2875,9 @@ Emacs is restarted by the session manager. @cindex notifications, on desktop Emacs is able to send @dfn{notifications} on systems that support the -freedesktop.org Desktop Notifications Specification and on MS-Windows. +freedesktop.org Desktop Notifications Specification, MS-Windows, +Haiku, and Android. + In order to use this functionality on POSIX hosts, Emacs must have been compiled with D-Bus support, and the @code{notifications} library must be loaded. @xref{Top, , D-Bus,dbus,D-Bus integration in Emacs}. @@ -2890,6 +2915,13 @@ must be the result of a previous @code{notifications-notify} call. @item :app-icon @var{icon-file} The file name of the notification icon. If set to @code{nil}, no icon is displayed. The default is @code{notifications-application-icon}. +If the value is a string, the function interprets it as a file name +and converts to absolute by using @code{expand-file-name}; if it is a +symbol, the function will use its name (which is useful when using the +Icon Naming Specification @footnote{For more information about icon +naming convention see +@uref{https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html, +Icon Naming Specification}}). @item :actions (@var{key} @var{title} @var{key} @var{title} ...) A list of actions to be applied. @var{key} and @var{title} are both @@ -3162,6 +3194,103 @@ This function removes the tray notification given by its unique @var{id}. @end defun +@cindex desktop notifications, Haiku +When Emacs runs under Haiku as a GUI program, it is also provides a +restricted pastiche of the D-Bus desktop notifications interface +previously addressed. The principle capabilities absent from the +function detailed below are call-back functions such as +@code{:actions}, @code{:on-action} and @code{:on-close}. + +@defun haiku-notifications-notify &rest params +This function sends a notification to the desktop notification server, +incorporating a number of parameters that are akin to some of those +accepted by @code{notifications-notify}. The parameters are: + +@table @code +@item :title @var{title} +@item :body @var{body} +@item :replaces-id @var{replaces-id} +@item :urgency @var{urgency} +These have the same meaning as they do when used in calls to +@code{notifications-notify}. + +@item :app-icon @var{app-icon} +This should be the file name designating an image file to use as the +icon for the notification displayed. If @code{nil}, the icon +presented will instead be Emacs's app icon. +@end table + +Its return value is a number identifying the notification, which can +be exploited as the @code{:replaces-id} parameter to a subsequent call +to this function. +@end defun + +@cindex desktop notifications, Android +When Emacs is built as an Android application package, displaying +notifications is facilitated by the function +@code{android-notifications-notify}. This function does not feature +call-backs, and has several idiosyncrasies, when compared to +@code{notifications-notify}. + +@defun android-notifications-notify &rest params +This function displays a desktop notification. @var{params} is a list +of parameters analogous to its namesake in +@code{notifications-notify}. The parameters are: + +@table @code +@item :title @var{title} +@item :body @var{body} +@item :replaces-id @var{replaces-id} +@item :on-action @var{on-action} +@item :on-cancel @var{on-close} +@item :actions @var{actions} +@item :timeout @var{timeout} +@item :resident @var{resident} +These have the same meaning as they do when used in calls to +@code{notifications-notify}, except that no more than three non-default +actions will be displayed. + +@item :urgency @var{urgency} +The set of accepted values for @var{urgency} is the same as with +@code{notifications-notify}, but the urgency applies to all +notifications displayed with the defined @var{group}, except under +Android 7.1 and earlier. + +@item :group @var{group} +@var{group} is a string that designates a category to which the +notification sent will belong. This category is reproduced within the +system's notification settings menus, but is ignored under Android 7.1 +and earlier. + +If @var{group} is nil or not present within @var{params}, it is +replaced by the string @samp{"Desktop Notifications"}. + +Callers should provide one stable combination of @var{urgency} and +@var{group} for each kind of notification they send, given that the +system may elect to disregard @var{urgency} if it does not match that +of any notification previously delivered to @var{group}. + +@item :icon @var{icon} +This parameter controls the symbolic icon the notification will be +displayed with. Its value is a string designating an icon within the +@code{android.R.drawable} system package. See +@uref{https://developer.android.com/reference/android/R.drawable,R.drawable +| Android Developers} for a list of such icons. + +If it is not provided within @var{params} or @var{icon} does not +exist, it defaults to @samp{"ic_dialog_alert"}. +@end table + +It returns a number identifying the notification, which may be +supplied as the @code{:replaces-id} parameter to a later call to this +function. + +If Emacs is not afforded the permission to display notifications +(@pxref{Android Environment,,, emacs, The GNU Emacs Manual}) under +Android 13 and later, any notifications sent will be silently +disregarded. +@end defun + @node File Notifications @section Notifications on File Changes @cindex file notifications @@ -3257,7 +3386,8 @@ reliably report file attribute changes when watching a directory. The @code{stopped} event means that watching the file has been discontinued. This could be because @code{file-notify-rm-watch} was called (see below), or because the file being watched was deleted, or -due to another error reported from the underlying library which makes +because the filesystem of the file being watched was unmounted, or due +to another error reported from the underlying library which makes further watching impossible. @var{file} and @var{file1} are the name of the file(s) whose event is |