diff options
| -rw-r--r-- | hurd/glibc/hurd-specific_api.mdwn | 357 |
1 files changed, 192 insertions, 165 deletions
diff --git a/hurd/glibc/hurd-specific_api.mdwn b/hurd/glibc/hurd-specific_api.mdwn index 7ead63cd..ed25a821 100644 --- a/hurd/glibc/hurd-specific_api.mdwn +++ b/hurd/glibc/hurd-specific_api.mdwn @@ -1,5 +1,5 @@ -[[!meta copyright="Copyright © 2002, 2007, 2008, 2010 Free Software Foundation, -Inc."]] +[[!meta copyright="Copyright © 2002, 2007, 2008, 2010, 2024 Free +Software Foundation, Inc."]] [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable id="license" text="Permission is granted to copy, distribute and/or modify this @@ -19,166 +19,193 @@ programs -- they are used to produce `.h` files. <!-- TODO. Need to convert this to a proper table. --tschwinge --> -<dl> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>getcwdir</b> (void);</tt></dt> - <p> - </p> - <dd>Get <tt>file_t</tt> port name of current working directory. See <tt>&lt;hurd/fs.defs&gt;</tt> and <tt>&lt;hurd/fs.h&gt;</tt>.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setcwdir</b> (file_t);</tt></dt> - <dd>Set current working directory.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>getcrdir</b> (void);</tt></dt> - <dd>Get <tt>file_t</tt> port name of current root directory.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setcrdir</b> (file_t);</tt></dt> - <p> - </p> - <dd>Set current root directory.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_lookup</b> (const char *file, int flags, mode_t mode);</tt></dt> - <dd>Open a port to FILE with the given FLAGS and MODE (see <tt>&lt;fcntl.h&gt;</tt>). The file lookup uses the current root and working directory. Returns a port to the file if successful; otherwise sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_lookup_under</b> (file_t startdir, const char *file, int flags, mode_t mode);</tt></dt> - <dd>Open a port to FILE with the given FLAGS and MODE (see <tt>&lt;fcntl.h&gt;</tt>). The file lookup uses the current root directory, but uses STARTDIR as the "working directory" for file relative names. Returns a port to the file if successful; otherwise sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_path_lookup</b> (const char *file_name, const char *path, int flags, mode_t mode, char **prefixed_name);</tt></dt> - <dd>Lookup FILE_NAME and return the node opened with FLAGS &amp; MODE (see <tt>hurd_file_name_lookup</tt> for details), but a simple file name (without any directory prefixes) will be consecutively prefixed with the pathnames in the <tt>:</tt> separated list PATH until one succeeds in a successful lookup. If none succeed, then the first error that wasn't ENOENT is returned, or ENOENT if no other errors were returned. If PREFIXED_NAME is non-NULL, then if the result is looked up directly, *PREFIXED_NAME is set to NULL, and if it is looked up using a prefix from PATH, *PREFIXED_NAME is set to malloc'd storage containing the prefixed name.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_split</b> (const char file, char **name);</tt></dt> - <dd>Split FILE into a directory and a name within the directory. The directory lookup uses the current root and working directory. If successful, stores in *NAME a pointer into FILE where the name within directory begins and returns a port to the directory; otherwise sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>directory_name_split</b> (const char *file, char **name);</tt></dt> - <p> - </p> - <dd>Split DIRECTORY into a parent directory and a name within the directory. This is the same as <tt>file_name_split</tt>, but ignores trailing slashes.</dd> - <p> - </p> - <dt><tt>FILE *</tt></dt> - <dt><tt><b>fopenport</b> (io_t port, const char *mode);</tt></dt> - <dd>Open a stream on a port. MODE is as for <tt>fopen</tt>. If successful, this consumes a user reference for PORT (which will be deallocated on fclose).</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>openport</b> (io_t port, int flags);</tt></dt> - <p> - </p> - <dd>Open a [[unix/file_descriptor]] on a [[microkernel/mach/port]]. FLAGS - are as for <tt>open</tt>; flags affected by <tt>io_set_openmodes</tt> are - not changed by this. If successful, this consumes a user reference for - PORT (which will be deallocated on close.) See - <tt>&lt;hurd/io.defs&gt;</tt> and - <tt>&lt;hurd/io.h&gt;</tt>. - </dd> - <p> - </p> - <dt><tt>task_t</tt></dt> - <dt><tt><b>pid2task</b> (pid_t pid);</tt></dt> - <p> - </p> - <dd>Return the task control port of process PID. On error, sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>pid_t</tt></dt> - <dt><tt><b>task2pid</b> (task_t task);</tt></dt> - <dd>Return the PID of the task whose control port is TASK. On error, sets <tt>errno</tt> and returns -1. </dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>geteuids</b> (int n, uid_t *uidset);</tt></dt> - <dd>Get the effective UID set.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>seteuids</b> (int n, const uid_t *uidset);</tt></dt> - <dd>Set the effective UID set.</dd> - <p> - </p> - <dt><tt>auth_t</tt></dt> - <dt><tt><b>getauth</b> (void);</tt></dt> - <dd>Get port name of current authentication server. See <tt>&lt;hurd/auth.defs&gt;</tt> and <tt>&lt;hurd/auth.h&gt;</tt>.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setauth</b> (auth_t);</tt></dt> - <p> - </p> - <dd>Set current authentication server.</dd> - <p> - </p> - <dt><tt>process_t</tt></dt> - <dt><tt><b>getproc</b> (void);</tt></dt> - <dd>Get port name of current process server. See <tt>&lt;hurd/process.defs&gt;</tt> and <tt>&lt;hurd/process.h&gt;</tt>.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setproc</b> (process_t);</tt></dt> - <p> - </p> - <dd>Set current process server.</dd> - <p> - </p> - <dt><tt>mach_port_t</tt></dt> - <dt><tt><b>getcttyid</b> (void);</tt></dt> - <dd>Get the CTTY port.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setcttyid</b> (mach_port_t);</tt></dt> - <dd>Set the CTTY port.</dd> - <p> - </p> - <dt><tt>kern_return_t</tt></dt> - <dt><tt><b>get_privileged_ports</b> (host_priv_t *host_priv_ptr, device_t *device_master_ptr);</tt></dt> - <dd>Fetch the host privileged port and device master port from the process server.</dd> - <p> - </p> - <dt><tt>mode_t</tt></dt> - <dt><tt><b>getumask</b> (void);</tt></dt> - <dd>Get the current `umask' value without changing it (this glibc functions is available only under GNU Hurd.)</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>vpprintf</b> (io_t port, const char *format, va_list arg);</tt></dt> - <dd>Write formatted output to PORT, a Mach port supporting the i/o protocol, according to the format string FORMAT, using the argument list in ARG.</dd> - <p> - </p> - <dt><tt>thread_t</tt></dt> - <dt><tt><b>hurd_thread_self</b> (void);</tt></dt> - <dd>Return the current thread's thread port. This is a cheap operation (no [[system call]]), but it relies on Hurd signal state being set up.</dd> - <p> - </p> - <dt><tt>error_t</tt></dt> - <dt><tt><b>hurd_thread_cancel</b> (thread_t thread);</tt></dt> - <p> - </p> - <dd>Cancel pending operations on THREAD. If it is doing an interruptible RPC, that RPC will now return EINTR; otherwise, the "cancelled" flag will be set, causing the next <tt>hurd_check_cancel</tt> call to return nonzero or the next interruptible RPC to return <tt>EINTR</tt> (whichever is called first).</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>hurd_check_cancel</b> (void);</tt></dt> - <p> - </p> - <dd>Test and clear the calling thread's "cancelled" flag.</dd> - <p> - </p> -</dl> + + file_t + getcwdir (void); + +Get `file_t` port name of the current working directory. See +`hurd.defs` and `hurd.h`. + + int + setcwdir (file_t); + +Set the current working directory. + + file_t + getcrdir (void); + +Get file_t port name of current root directory. + + int + setcrdir (file_t); + +Set current root directory. + + file_t + file_name_lookup (const char *file, int flags, mode_t mode); + +Open a port to `FILE` with the given `FLAGS` and `MODE` (see +`fcntl.h`). The file lookup uses the current root and working +directory. Returns a port to the file if successful; otherwise sets +`errno` and returns `MACH_PORT_NULL`. + + file_t + file_name_lookup_under (file_t startdir, const char *file, + int flags, mode_t mode); + +Open a port to `FILE` with the given `FLAGS` and `MODE` (see +`fcntl.h`). The file lookup uses the current root directory, but uses +`STARTDIR` as the "working directory" for file relative names. Returns +a port to the file if successful; otherwise sets errno and returns +`MACH_PORT_NULL`. + + file_t + file_name_path_lookup (const char *file_name, const char *path, + int flags, mode_t mode, + char **prefixed_name); + +Lookup `FILE_NAME` and return the node opened with `FLAGS` & `MODE` +(see `hurd_file_name_lookup` for details), but a simple file name +(without any directory prefixes) will be consecutively prefixed with +the pathnames in the : separated list `PATH` until one succeeds in a +successful lookup. If none succeed, then the first error that wasn't +`ENOENT` is returned, or `ENOENT` if no other errors were returned. If +`PREFIXED_NAME` is non-NULL, then if the result is looked up directly, +`*PREFIXED_NAME` is set to NULL, and if it is looked up using a prefix +from `PATH`, `*PREFIXED_NAME` is set to malloc'd storage containing +the prefixed name. + + file_t + file_name_split (const char file, char **name); + +Split `FILE` into a directory and a name within the directory. The +directory lookup uses the current root and working directory. If +successful, stores in `*NAME` a pointer into `FILE` where the name +within directory begins and returns a port to the directory; otherwise +sets errno and returns `MACH_PORT_NULL`. + + file_t + directory_name_split (const char *file, char **name); + +Split `DIRECTORY` into a parent directory and a name within the +directory. This is the same as `file_name_split`, but ignores trailing +slashes. + + FILE * + fopenport (io_t port, const char *mode); + +Open a stream on a port. `MODE` is as for `fopen`. If successful, this +consumes a user reference for `PORT` (which will be deallocated on +`fclose`). + + int + openport (io_t port, int flags); + +Open a [[file descriptor|unix/file_descriptor]] on a +[[port|microkernel/mach/port]]. `FLAGS` are as for open; flags +affected by `io_set_openmodes` are not changed by this. If successful, +this consumes a user reference for `PORT` (which will be deallocated +on close.) See `hurd/io.defs` and `hurd/io.h`. + + task_t + pid2task (pid_t pid); + +Return the task control port of process `PID`. On error, sets errno and +returns `MACH_PORT_NULL`. + + pid_t + task2pid (task_t task); + +Return the `PID` of the task whose control port is `TASK`. On error, sets +errno and returns -1. + + int + geteuids (int n, uid_t *uidset); + +Get the effective UID set. + + int + seteuids (int n, const uid_t *uidset); + +Set the effective UID set. + + auth_t + getauth (void); + +Get port name of current authentication server. See +`hurd/auth.defs` and `hurd/auth.h`. + + int + setauth (auth_t); + +Set current authentication server. + + process_t + getproc (void); + +Get port name of current process server. See `hurd/process.defs` +and `hurd/process.h`. `process_t` is a port to the proc server, by +which RPCs are made to the proc server. It is also a way to represent +a task when communicating with the proc server. Each task has its own +port by which it communicates with the process server under the +identity of the task. You can pass a `process_t` to another process, +and then that process can call RPCs with the process server with the +identity of the original task that pasted the port. +<!-- I got the information about process_t from this irc chat log +https://logs.guix.gnu.org/hurd/2021-03-18.log#105247 --> + + int + setproc (process_t); + +Set current process server. + + mach_port_t + getcttyid (void); + +Get the CTTY port. + + int + setcttyid (mach_port_t); + +Set the CTTY port. + + kern_return_t + get_privileged_ports (host_priv_t *host_priv_ptr, + device_t *device_master_ptr); + +Fetch the host privileged port and device master port from the process +server. + + mode_t + getumask (void); + +Get the current `umask` value without changing it (this glibc +functions is available only under GNU Hurd.) + + int + vpprintf (io_t port, const char *format, va_list arg); + +Write formatted output to `PORT`, a Mach port supporting the i/o +protocol, according to the format string `FORMAT`, using the argument +list in `ARG`. + + thread_t + hurd_thread_self (void); + +Return the current thread's thread port. This is a cheap operation (no +[[system call|system_call]]), but it relies on Hurd signal state being +set up. + + error_t + hurd_thread_cancel (thread_t thread); + +Cancel pending operations on `THREAD`. If it is doing an interruptible +RPC, that RPC will now return `EINTR`; otherwise, the "cancelled" flag +will be set, causing the next `hurd_check_cancel` call to return +nonzero or the next interruptible RPC to return `EINTR` (whichever is +called first). + + int + hurd_check_cancel (void); + +Test and clear the calling thread's "cancelled" flag. |