Docs for Hurd functions in libc (<hurd.h>)

[Alfred M. Szmidt]

Hi,

while waiting for GDB to compile and wanting to be atleast a bit
productive I started extracting the functions related to the Hurd in
libc.  All of it is really just a quick cut and paste from hurd.h, but
some functions do need to get a small blurb about what they do.  Since
I'm giving up with waiting for this silly compile job to finish, I
thought that maybe someone would be interested in helping out.
Comments are as always very welcome; specially from people that are
quite unfamiliar with the functions (which have a easier job pointing
out where information is lacking).

Cheers.

===File ~/hurd_libc.texi====================================
@deftypefun process_t getproc (void)
FIXME
@end deftypefun

@deftypefun file_t getcwdir (void)
FIXME
@end deftypefun

@deftypefun file_t getcrdir (void)
FIXME
@end deftypefun

@deftypefun auth_t getauth (void)
FIXME
@end deftypefun

@deftypefun mach_port_t getcttyid (void)
FIXME
@end deftypefun

@deftypefun int setproc (process_t FIXME)
FIXME
@end deftypefun

@deftypefun int setcwdir (file_t FIXME)
FIXME
@end deftypefun

@deftypefun setcrdir (file_t FIXME)
FIXME
@end deftypefun

@deftypefun int setcttyid (mach_port_t FIXME)
FIXME
@end deftypefun

@deftypefun int setauth (@w{auth_t @var{new}})
Does reauth with the proc server and fd io servers.
@end deftypefun

@deftypefun int geteuids (@w{int @var{n}, uid_t *@var{uidset}})
Get the effective UID set.
@end deftypefun

@deftypefun int seteuids (@w{int @var{n}, const uid_t *@var{uidset}})
Set the effective UID set.
@end deftypefun

@deftypefun file_t file_name_split (@w{const char *@var{file}, char 
**@var{name}})
Split @var{FILE} into a directory and a name within the directory.
The directory lookup uses the current root and working directory.  If
successful, stores in *@var{NAME} a pointer into @var{FILE} where the
name within directory begins and returns a port to the directory;
otherwise sets `errno' and returns @code{MACH_PORT_NULL}.
@end deftypefun

@deftypefun file_t directory_name_split (@w{const char *@var{file}, char 
**@var{name}})
Split @var{FILE} into a parent directory and a name within the
directory.  This is the same as file_name_split, but ignores trailing
slashes.
@end deftypefun

@deftypefun file_t file_name_lookup (@w{const char *@var{file}, int 
@var{flags}, mode_t @var{mode}})
Open a port to @var{FILE} with the given @var{FLAGS} and @var{MODE}
(see <fcntl.h> FIXME: xref).  The file lookup uses the current root
and working directory.  Returns a port to the file if successful;
otherwise sets `errno' and returns @code{MACH_PORT_NULL}.
@end deftypefun

@deftypefun file_t file_name_lookup_under (@w{file_t @var{startdir}, const char 
*@var{file}, int @var{flags}, mode_t @var{mode}})
Open a port to @var{FILE} with the given @var{FLAGS} and @var{MODE}
(see <fcntl.h> FIXME: xref).  The file lookup uses the current root
directory, but uses @var{STARTDIR} as the "working directory" for file
relative names.  Returns a port to the file if successful; otherwise
sets `errno' and returns @code{MACH_PORT_NULL}.
@end deftypefun

@deftypefun file_t file_name_path_lookup (@w{const char *@var{file_name}, const 
char *@var{path}, int @var{flags}, mode_t @var{mode}, char 
**@var{prefixed_name}})
Lookup @var{FILE_NAME} and return the node opened with @var{FLAGS} and
@var{MODE} (see hurd_file_name_lookup for details FIXME: xref ???),
but a simple file name (without any directory prefixes) will be
consecutively prefixed with the pathnames in the `:' separated list
@code{PATH} until one succeeds in a successful lookup.  If none
succeed, then the first error that wasn't @code{ENOENT} is returned,
or @code{ENOENT} if no other errors were returned.  If
@var{PREFIXED_NAME} is non-@code{NULL}, then if the result is looked
up directly, *@var{PREFIXED_NAME} is set to NULL, and if it is looked
up using a prefix from @code{PATH}, *@var{PREFIXED_NAME} is set to
malloc'd storage containing the prefixed name.
@end deftypefun

@deftypefun int openport (@w{io_t @var{port}, int @var{flags}})
Open a file descriptor on a port.  @var{FLAGS} are as for `open';
flags affected by io_set_openmodes are not changed by this.  If
successful, this consumes a user reference for @var{PORT} (which will
be deallocated on close).
@end deftypefun

@deftypefun FILE *fopenport (@w{io_t @var{port}, const char *@var{mode}})
Open a stream on a port.  @var{MODE} is as for `fopen'.  If
successful, this consumes a user reference for @var{PORT} (which will
be deallocated on fclose).
@end deftypefun

@deftypefun error_t hurd_sig_post (@w{pid_t @var{pid}, int @var{sig}, 
mach_port_t @var{refport}})
Send a `sig_post' RPC to process number @var{PID}.  If @var{PID} is
zero, send the message to all processes in the current process's
process group.  If @var{PID} is < -1, send @var{SIG} to all processes
in process group - PID.  @var{SIG} and @var{REFPORT} are passed along
in the request message.
@end deftypefun

@deftypefun kern_return_t get_privileged_ports (@w{mach_port_t 
*@var{host_priv_ptr}, device_t *@var{device_master_ptr}})
Fetch the host privileged port and device master port from the proc
server.  They are fetched only once and then cached in the variables
below.  A special program that gets them from somewhere other than the
proc server (such as a bootstrap file-system) can set these variables
to install the ports.
@end deftypefun

@deftypefun thread_t hurd_thread_self (void)
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.
@end deftypefun

@deftypefun error_t hurd_thread_cancel (thread_t @var{thread}})
Cancel pending operations on @var{THREAD}.  If it is doing an
interruptible RPC, that RPC will now return @code{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
@code{EINTR} (whichever is called first).
@end deftypefun

@deftypefun int hurd_check_cancel (void)
Test and clear the calling thread's "cancelled" flag.
@end deftypefun

@deftypefun int vpprintf (@w{io_t @var{port}, const char *@var{format}, va_list 
@var{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 @var{ARG}.
@end deftypefun
============================================================