source: project/wiki/man/5/Module (chicken process-context) @ 34492

Last change on this file since 34492 was 34492, checked in by sjamaan, 4 years ago

man/5: Update note about opening directories from FD on Windows to mention cygwin emulation

File size: 8.3 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Module (chicken process-context)
5
6This module provides access to the current process context.
7
8=== Information about the program's invocation
9
10==== argv
11
12<procedure>(argv)</procedure>
13
14Return a list of all supplied command-line arguments. The first item in
15the list is a string containing the name of the executing program. The
16other items are the arguments passed to the application. It depends on
17the host-shell whether arguments are expanded ('globbed') or not.
18
19=== command-line-arguments
20
21<parameter>(command-line-arguments)</parameter>
22
23Contains the list of arguments passed to this program, with the name of
24the program and any runtime options (all options starting with {{-:}})
25removed.
26
27==== executable-pathname
28
29<procedure>(executable-pathname)</procedure>
30
31Returns a full pathname of the currently-running executable, or {{#f}}
32if it couldn't be determined. When evaluating code in the interpreter,
33this will be a path to {{csi}}.
34
35=== program-name
36
37<parameter>(program-name)</parameter>
38
39The name of the currently executing program. This is equivalent to
40{{(car (argv))}} for compiled programs or the filename following the
41{{-script}} option in interpreted scripts.
42
43
44
45=== Process shutdown
46
47==== emergency-exit
48
49<procedure>(emergency-exit [CODE])</procedure>
50
51Exits the current process without flushing any buffered output (using
52the C function {{_exit}}).  Note that the {{exit-handler}} is not called
53when this procedure is invoked. The optional exit status code {{CODE}}
54defaults to {{0}}.
55
56
57==== exit
58
59<procedure>(exit [CODE])</procedure>
60
61Exit the running process and return exit-code, which defaults to 0
62(Invokes {{exit-handler}}).
63
64Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
65
66
67=== exit-handler
68
69<parameter>(exit-handler)</parameter>
70
71A procedure of a single optional argument. When {{exit}} is called,
72then this procedure will be invoked with the exit-code as argument. The
73default behavior is to terminate the program.
74
75Note that this handler is ''not'' invoked when {{emergency-exit}} is
76used.
77
78
79=== implicit-exit-handler
80
81<parameter>(implicit-exit-handler)</parameter>
82
83A procedure of no arguments. When the last toplevel expression of the
84program has executed, then the value of this parameter is called. The
85default behaviour is to invoke all pending finalizers.
86
87
88==== on-exit
89
90<procedure>(on-exit THUNK)</procedure>
91
92Schedules the zero-argument procedures {{THUNK}} to be executed before
93the process exits, either explicitly via {{exit}} or implicitly after execution
94of the last top-level form. Note that finalizers for unreferenced finalized
95data are run before exit procedures.
96
97
98=== Access to environment variables
99
100==== get-environment-variables
101
102<procedure>(get-environment-variables)</procedure>
103
104Returns a association list of the environment variables and their
105current values (see also [[http://srfi.schemers.org/srfi-98/|SRFI-98]]).
106
107==== get-environment-variable
108
109<procedure>(get-environment-variable STRING)</procedure><br>
110
111Returns the value of the environment variable {{STRING}} or
112{{#f}} if that variable is not defined. See also [[http://srfi.schemers.org/srfi-98/|SRFI-98]].
113
114==== set-environment-variable!
115
116<procedure>(set-environment-variable! VARIABLE VALUE)</procedure>
117
118Sets the environment variable named {{VARIABLE}} to
119{{VALUE}}. Both arguments should be strings. If the variable is
120not defined in the environment, a new definition is created.
121
122==== unset-environment-variable!
123
124<procedure>(unset-environment-variable! VARIABLE)</procedure>
125
126Removes the definition of the environment variable {{VARIABLE}} from
127the environment of the current process. If the variable is not defined,
128nothing happens.
129
130
131=== Process filesystem context
132
133==== change-directory
134
135<procedure>(change-directory NAME)</procedure>
136<procedure>(set! (current-directory) NAME)</procedure>
137
138Changes the current working directory to {{NAME}}.
139
140==== change-directory*
141
142<procedure>(change-directory* FD)</procedure>
143<procedure>(set! (current-directory) FD)</procedure>
144
145Changes the current working directory to the one represented by the
146file-descriptor {{FD}}, which should be an exact integer.
147
148'''NOTE''': Windows does not allow {{{open}}} on directories, so while
149technically it is supported, in practice you cannot use this procedure
150on native Windows builds (on cygwin it works because cygwin emulates
151this).
152
153==== current-directory
154
155<procedure>(current-directory)</procedure>
156
157Returns the name of the current working directory.
158
159==== set-root-directory!
160
161<procedure>(set-root-directory! STRING)</procedure>
162
163Sets the root directory for the current process to the path given in
164{{STRING}} (using the {{chroot}} function).  If the current process
165has no root permissions, the operation will fail.
166
167'''NOTE''': On native Windows builds (all except cygwin), this
168procedure is unimplemented and will raise an error.
169
170
171=== Retrieving user & group information
172
173==== current-user-id
174
175<procedure>(current-user-id)</procedure>
176 [setter] (set! (current-user-id) UID)
177
178Get or set the real user-id of the current process. The procedure corresponds to the getuid and setuid C functions.
179
180'''NOTE''': On native Windows builds (all except cygwin), this
181procedure is unimplemented and will raise an error.
182
183==== current-user-id
184
185<procedure>(current-user-name)</procedure>
186
187Get the login name corresponding to the real user-id of the current
188process from the system password database.
189
190On Windows, there's no user-id and no distinction between real and
191effective user, but this procedure ''will'' return the username
192associated with the current process, so it is safe to use.
193
194
195==== current-effective-user-id
196
197<procedure>(current-effective-user-id)</procedure>
198 [setter] (set! (current-effective-user-id) UID)
199
200Get or set the effective user-id of the current process.
201
202'''NOTE''': On native Windows builds (all except cygwin), this
203procedure is unimplemented and will raise an error.
204
205==== current-user-id
206
207<procedure>(current-effective-user-name)</procedure>
208
209Get the login name corresponding to the effective user-id of the
210current process from the system password database.
211
212'''NOTE''': On native Windows builds (all except cygwin), this
213procedure is unimplemented and will raise an error.
214
215==== current-group-id
216
217<procedure>(current-group-id)</procedure>
218 [setter] (set! (current-group-id) GID)
219
220Get or set the real group-id of the current process.
221
222'''NOTE''': On native Windows builds (all except cygwin), this
223procedure is unimplemented and will raise an error.
224
225==== current-effective-group-id
226
227<procedure>(current-effective-group-id)</procedure>
228 [setter] (set! (current-effective-group-id) GID)
229
230Get or set the effective group-id of the current process.
231ID can be found, then {{#f}} is returned.
232
233'''NOTE''': On native Windows builds (all except cygwin), this
234procedure is unimplemented and will raise an error.
235
236=== Process identity
237
238==== current-process-id
239
240<procedure>(current-process-id)</procedure>
241
242Returns the process ID of the current process.
243
244==== parent-process-id
245
246<procedure>(parent-process-id)</procedure>
247
248Returns the process ID of the parent of the current process.
249
250'''NOTE''': On native Windows builds (all except cygwin), this
251procedure is unimplemented and will raise an error.
252
253==== process-group-id
254
255<procedure>(process-group-id PID)</procedure>
256 [setter] (set! (process-group-id PID) PGID)
257
258Get or set the process group ID of the process specified by {{PID}}.
259
260'''NOTE''': On native Windows builds (all except cygwin), this
261procedure is unimplemented and will raise an error.
262
263==== user-information
264
265<procedure>(user-information USER [AS-VECTOR])</procedure>
266
267If {{USER}} specifes a valid username (as a string) or user ID, then
268the user database is consulted and a list of 7 values are returned:
269the user-name, the encrypted password, the user ID, the group ID, a
270user-specific string, the home directory and the default shell. When
271{{AS-VECTOR}} is {{#t}} a vector of 7 elements is returned instead of
272a list. If no user with this name or id then {{#f}} is returned.
273
274Note: on Android systems, the user-specific string is always {{""}},
275since {{pw_gecos}} is not available in the C {{passwd}} struct on that
276platform.
277
278'''NOTE''': On native Windows builds (all except cygwin), this
279procedure is unimplemented and will raise an error.
280
281
282---
283Previous: [[Module (chicken process signal)]]
284
285Next: [[Module (chicken random)]]
Note: See TracBrowser for help on using the repository browser.