diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/intro.texi | 2 | ||||
| -rw-r--r-- | manual/message.texi | 66 | ||||
| -rw-r--r-- | manual/process.texi | 5 | ||||
| -rw-r--r-- | manual/signal.texi | 2 | ||||
| -rw-r--r-- | manual/startup.texi | 183 |
5 files changed, 223 insertions, 35 deletions
diff --git a/manual/intro.texi b/manual/intro.texi index b3c1b05614..b133560ac2 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -674,7 +674,7 @@ signal is delivered, and how to prevent signals from arriving during critical sections of your program. @item -@ref{Process Startup}, tells how your programs can access their +@ref{Program Basics}, tells how your programs can access their command-line arguments and environment variables. @item diff --git a/manual/message.texi b/manual/message.texi index 446e6d7b56..455b8e02e9 100644 --- a/manual/message.texi +++ b/manual/message.texi @@ -764,13 +764,15 @@ basic functionally is equivalent. There are functions of the following categories: @menu -* Translation with gettext:: What has to be done to translate a message. -* Locating gettext catalog:: How to determine which catalog to be used. -* Advanced gettext functions:: Additional functions for more complicated - situations. -* GUI program problems:: How to use @code{gettext} in GUI programs. -* Using gettextized software:: The possibilities of the user to influence - the way @code{gettext} works. +* Translation with gettext:: What has to be done to translate a message. +* Locating gettext catalog:: How to determine which catalog to be used. +* Advanced gettext functions:: Additional functions for more complicated + situations. +* Charset conversion in gettext:: How to specify the output character set + @code{gettext} uses. +* GUI program problems:: How to use @code{gettext} in GUI programs. +* Using gettextized software:: The possibilities of the user to influence + the way @code{gettext} works. @end menu @node Translation with gettext @@ -1045,7 +1047,7 @@ running program does not depend on the user setting an environment variable. The @code{bindtextdomain} function can be used several times and if the -@var{domainname} argument is different the previously bounded domains +@var{domainname} argument is different the previously bound domains will not be overwritten. If the program which wish to use @code{bindtextdomain} at some point of @@ -1359,6 +1361,52 @@ Slovenian @end table +@node Charset conversion in gettext +@subsubsection How to specify the output character set @code{gettext} uses + +@code{gettext} not only looks up a translation in a message catalog. It +also converts the translation on the fly to the desired output character +set. This is useful if the user is working in a different character set +than the translator who created the message catalog, because it avoids +distributing variants of message catalogs which differ only in the +character set. + +The output character set is, by default, the value of @code{nl_langinfo +(CODESET)}, which depends on the @code{LC_CTYPE} part of the current +locale. But programs which store strings in a locale independent way +(e.g. UTF-8) can request that @code{gettext} and related functions +return the translations in that encoding, by use of the +@code{bind_textdomain_codeset} function. + +Note that the @var{msgid} argument to @code{gettext} is not subject to +character set conversion. Also, when @code{gettext} does not find a +translation for @var{msgid}, it returns @var{msgid} unchanged -- +independently of the current output character set. It is therefore +recommended that all @var{msgid}s be US-ASCII strings. + +@comment libintl.h +@comment GNU +@deftypefun {char *} bind_textdomain_codeset (const char *@var{domainname}, const char *@var{codeset}) +The @code{bind_textdomain_codeset} function can be used to specify the +output character set for message catalogs for domain @var{domainname}. + +If the @var{codeset} parameter is the null pointer, +@code{bind_textdomain_codeset} returns the currently selected codeset +for the domain with the name @var{domainname}. It returns @code{NULL} if +no codeset has yet been selected. + +The @code{bind_textdomain_codeset} function can be used several times. +If used multiple times with the same @var{domainname} argument, the +later call overrides the settings made by the earlier one. + +The @code{bind_textdomain_codeset} function returns a pointer to a +string containing the name of the selected codeset. The string is +allocated internally in the function and must not be changed by the +user. If the system went out of core during the execution of +@code{bind_textdomain_codeset}, the return value is @code{NULL} and the +global variable @var{errno} is set accordingly. @end deftypefun + + @node GUI program problems @subsubsection How to use @code{gettext} in GUI programs @@ -1589,7 +1637,7 @@ to work: @{ textdomain ("test-package"); bindtextdomain ("test-package", "/usr/local/share/locale"); - puts (gettext ("Hello, world!"); + puts (gettext ("Hello, world!")); @} @end smallexample diff --git a/manual/process.texi b/manual/process.texi index b9f255117d..aa5f7270d4 100644 --- a/manual/process.texi +++ b/manual/process.texi @@ -1,4 +1,4 @@ -@node Processes, Job Control, Process Startup, Top +@node Processes, Job Control, Program Basics, Top @c %MENU% How to create processes and run other programs @chapter Processes @@ -276,6 +276,9 @@ This section describes the @code{exec} family of functions, for executing a file as a process image. You can use these functions to make a child process execute a new program after it has been forked. +To see the effects of @code{exec} from the point of view of the called +program, @xref{Program Basics}. + @pindex unistd.h The functions in this family differ in how you specify the arguments, but otherwise they all do the same thing. They are declared in the diff --git a/manual/signal.texi b/manual/signal.texi index 95e7a363c0..94972fa43d 100644 --- a/manual/signal.texi +++ b/manual/signal.texi @@ -1,4 +1,4 @@ -@node Signal Handling, Process Startup, Non-Local Exits, Top +@node Signal Handling, Program Basics, Non-Local Exits, Top @c %MENU% How to send, block, and handle signals @chapter Signal Handling diff --git a/manual/startup.texi b/manual/startup.texi index 27459989cb..8f4fd23bc9 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -1,25 +1,43 @@ -@node Process Startup, Processes, Signal Handling, Top +@node Program Basics, Processes, Signal Handling, Top @c %MENU% Writing the beginning and end of your program -@chapter Process Startup and Termination +@chapter The Basic Program/System Interface @cindex process +@cindex program +@cindex address space +@cindex thread of control @dfn{Processes} are the primitive units for allocation of system resources. Each process has its own address space and (usually) one thread of control. A process executes a program; you can have multiple processes executing the same program, but each process has its own copy of the program within its own address space and executes it -independently of the other copies. - -This chapter explains what your program should do to handle the startup -of a process, to terminate its process, and to receive information -(arguments and the environment) from the parent process. +independently of the other copies. Though it may have multiple threads +of control within the same program and a program may be composed of +multiple logically separate modules, a process always executes exactly +one program. + +Note that we are using a specific definition of ``program'' for the +purposes of this manual, which corresponds to a common definition in the +context of Unix system. In popular usage, ``program'' enjoys a much +broader definition; it can refer for example to a system's kernel, an +editor macro, a complex package of software, or a discrete section of +code executing within a process. + +Writing the program is what this manual is all about. This chapter +explains the most basic interface between your program and the system +that runs, or calls, it. This includes passing of parameters (arguments +and environment) from the system, requesting basic services from the +system, and telling the system the program is done. + +A program starts another program with the @code{exec} family of system calls. +This chapter looks at program startup from the execee's point of view. To +see the event from the execor's point of view, @xref{Executing a File}. @menu * Program Arguments:: Parsing your program's command-line arguments. -* Environment Variables:: How to access parameters inherited from - a parent process. -* Program Termination:: How to cause a process to terminate and - return status information to its parent. +* Environment Variables:: Less direct parameters affecting your program +* System Calls:: Requesting service from the system +* Program Termination:: Telling the system you're done; return status @end menu @node Program Arguments @@ -72,7 +90,7 @@ int main (int @var{argc}, char *@var{argv}[], char *@var{envp}) @end smallexample The first two arguments are just the same. The third argument -@var{envp} gives the process's environment; it is the same as the value +@var{envp} gives the program's environment; it is the same as the value of @code{environ}. @xref{Environment Variables}. POSIX.1 does not allow this three-argument form, so to be portable it is best to write @code{main} to take two arguments, and use the value of @code{environ}. @@ -438,7 +456,7 @@ this lets the user specify the value. This is the name that the user used to log in. Since the value in the environment can be tweaked arbitrarily, this is not a reliable way to -identify the user who is running a process; a function like +identify the user who is running a program; a function like @code{getlogin} (@pxref{Who Logged In}) is better for that purpose. For most purposes, it is better to use @code{LOGNAME}, precisely because @@ -562,6 +580,113 @@ reordering of command line arguments by @code{getopt} and @c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS @end table +@node System Calls +@section System Calls + +@cindex system call +A system call is a request for service that a program makes of the +kernel. The service is generally something that only the kernel has +the privilege to do, such as doing I/O. Programmers don't normally +need to be concerned with system calls because there are functions in +the GNU C library to do virtually everything that system calls do. +These functions work by making system calls themselves. For example, +there is a system call that changes the permissions of a file, but +you don't need to know about it because you can just use the GNU C +library's @code{chmod} function. + +@cindex kernel call +System calls are sometimes called kernel calls. + +However, there are times when you want to make a system call explicitly, +and for that, the GNU C library provides the @code{syscall} function. +@code{syscall} is harder to use and less portable than functions like +@code{chmod}, but easier and more portable than coding the system call +in assembler instructions. + +@code{syscall} is most useful when you are working with a system call +which is special to your system or is newer than the GNU C library you +are using. @code{syscall} is implemented in an entirely generic way; +the function does not know anything about what a particular system +call does or even if it is valid. + +The description of @code{syscall} in this section assumes a certain +protocol for system calls on the various platforms on which the GNU C +library runs. That protocol is not defined by any strong authority, but +we won't describe it here either because anyone who is coding +@code{syscall} probably won't accept anything less than kernel and C +library source code as a specification of the interface between them +anyway. + + +@code{syscall} is declared in @file{unistd.h}. + +@comment unistd.h +@comment ??? +@deftypefun long int syscall (long int @var{sysno}, ...) + +@code{syscall} performs a generic system call. + +@cindex system call number +@var{sysno} is the system call number. Each kind of system call is +identified by a number. Macros for all the possible system call numbers +are defined in @file{sys/syscall.h} + +The remaining arguments are the arguments for the system call, in +order, and their meanings depend on the kind of system call. Each kind +of system call has a definite number of arguments, from zero to five. +If you code more arguments than the system call takes, the extra ones to +the right are ignored. + +The return value is the return value from the system call, unless the +system call failed. In that case, @code{syscall} returns @code{-1} and +sets @code{errno} to an error code that the system call returned. Note +that system calls do not return @code{-1} when they succeed. +@cindex errno + +If you specify an invalid @var{sysno}, @code{syscall} returns @code{-1} +with @code{errno} = @code{ENOSYS}. + +Example: + +@smallexample + +#include <unistd.h> +#include <sys/syscall.h> +#include <errno.h> + +... + +int rc; + +rc = syscall(SYS_chmod, "/etc/passwd", 0444); + +if (rc == -1) + fprintf(stderr, "chmod failed, errno = %d\n", errno); + +@end smallexample + +This, if all the compatibility stars are aligned, is equivalent to the +following preferable code: + +@smallexample + +#include <sys/types.h> +#include <sys/stat.h> +#include <errno.h> + +... + +int rc; + +rc = chmod("/etc/passwd", 0444); +if (rc == -1) + fprintf(stderr, "chmod failed, errno = %d\n", errno); + +@end smallexample + +@end deftypefun + + @node Program Termination @section Program Termination @cindex program termination @@ -595,15 +720,19 @@ a signal that kills the program. @node Normal Termination @subsection Normal Termination -A process terminates normally when the program calls @code{exit}. -Returning from @code{main} is equivalent to calling @code{exit}, and -the value that @code{main} returns is used as the argument to @code{exit}. +A process terminates normally when its program signals it is done by +calling @code{exit}. Returning from @code{main} is equivalent to +calling @code{exit}, and the value that @code{main} returns is used as +the argument to @code{exit}. @comment stdlib.h @comment ISO @deftypefun void exit (int @var{status}) -The @code{exit} function terminates the process with status -@var{status}. This function does not return. +The @code{exit} function tells the system that the program is done, which +causes it to terminate the process. + +@var{status} is the program's exit status, which becomes part of the +process' termination status. This function does not return. @end deftypefun Normal termination causes the following actions: @@ -695,6 +824,12 @@ kinds of "non-success". For example, @code{diff} uses status value mean that there was difficulty in opening the files. @end deftypevr +Don't confuse a program's exit status with a process' termination status. +There are lots of ways a process can terminate besides having it's program +finish. In the event that the process termination @emph{is} caused by program +termination (i.e. @code{exit}), though, the program's exit status becomes +part of the process' termination status. + @node Cleanups on Exit @subsection Cleanups on Exit @@ -796,8 +931,8 @@ This function was introduced in @w{ISO C99} and is declared in @file{stdlib.h}. @end deftypefun -When a process terminates for any reason---either by an explicit -termination call, or termination as a result of a signal---the +When a process terminates for any reason---either because the program +terminates, or as a result of a signal---the following things happen: @itemize @bullet @@ -807,9 +942,11 @@ Note that streams are not flushed automatically when the process terminates; see @ref{I/O on Streams}. @item -The low-order 8 bits of the return status code are saved to be reported -back to the parent process via @code{wait} or @code{waitpid}; see -@ref{Process Completion}. +A process exit status is saved to be reported back to the parent process +via @code{wait} or @code{waitpid}; see @ref{Process Completion}. If the +program exited, this status includes as its low-order 8 bits the program +exit status. + @item Any child processes of the process being terminated are assigned a new |