1 | @c |
---|
2 | @c COPYRIGHT (c) 1988-2002. |
---|
3 | @c On-Line Applications Research Corporation (OAR). |
---|
4 | @c All rights reserved. |
---|
5 | @c |
---|
6 | @c $Id$ |
---|
7 | @c |
---|
8 | |
---|
9 | @chapter Process Environment Manager |
---|
10 | |
---|
11 | @section Introduction |
---|
12 | |
---|
13 | The process environment manager is responsible for providing the |
---|
14 | functions related to user and group Id management. |
---|
15 | |
---|
16 | The directives provided by the process environment manager are: |
---|
17 | |
---|
18 | @itemize @bullet |
---|
19 | @item @code{getpid} - Get Process ID |
---|
20 | @item @code{getppid} - Get Parent Process ID |
---|
21 | @item @code{getuid} - Get User ID |
---|
22 | @item @code{geteuid} - Get Effective User ID |
---|
23 | @item @code{getgid} - Get Real Group ID |
---|
24 | @item @code{getegid} - Get Effective Group ID |
---|
25 | @item @code{setuid} - Set User ID |
---|
26 | @item @code{setgid} - Set Group ID |
---|
27 | @item @code{getgroups} - Get Supplementary Group IDs |
---|
28 | @item @code{getlogin} - Get User Name |
---|
29 | @item @code{getlogin_r} - Reentrant Get User Name |
---|
30 | @item @code{getpgrp} - Get Process Group ID |
---|
31 | @item @code{setsid} - Create Session and Set Process Group ID |
---|
32 | @item @code{setpgid} - Set Process Group ID for Job Control |
---|
33 | @item @code{uname} - Get System Name |
---|
34 | @item @code{times} - Get Process Times |
---|
35 | @item @code{getenv} - Get Environment Variables |
---|
36 | @item @code{setenv} - Set Environment Variables |
---|
37 | @item @code{ctermid} - Generate Terminal Pathname |
---|
38 | @item @code{ttyname} - Determine Terminal Device Name |
---|
39 | @item @code{ttyname_r} - Reentrant Determine Terminal Device Name |
---|
40 | @item @code{isatty} - Determine if File Descriptor is Terminal |
---|
41 | @item @code{sysconf} - Get Configurable System Variables |
---|
42 | @end itemize |
---|
43 | |
---|
44 | @section Background |
---|
45 | |
---|
46 | @subsection Users and Groups |
---|
47 | |
---|
48 | RTEMS provides a single process, multi-threaded execution environment. |
---|
49 | In this light, the notion of user and group is somewhat without meaning. |
---|
50 | But RTEMS does provide services to provide a synthetic version of |
---|
51 | user and group. By default, a single user and group is associated |
---|
52 | with the application. Thus unless special actions are taken, |
---|
53 | every thread in the application shares the same user and group Id. |
---|
54 | The initial rationale for providing user and group Id functionality |
---|
55 | in RTEMS was for the filesystem infrastructure to implement |
---|
56 | file permission checks. The effective user/group Id capability |
---|
57 | has since been used to implement permissions checking by |
---|
58 | the @code{ftpd} server. |
---|
59 | |
---|
60 | In addition to the "real" user and group Ids, a process may |
---|
61 | have an effective user/group Id. This allows a process to |
---|
62 | function using a more limited permission set for certain operations. |
---|
63 | |
---|
64 | @subsection User and Group Names |
---|
65 | |
---|
66 | POSIX considers user and group Ids to be a unique integer that |
---|
67 | may be associated with a name. This is usually accomplished |
---|
68 | via a file named @code{/etc/passwd} for user Id mapping and |
---|
69 | @code{/etc/groups} for group Id mapping. Again, although |
---|
70 | RTEMS is effectively a single process and thus single user |
---|
71 | system, it provides limited support for user and group |
---|
72 | names. When configured with an appropriate filesystem, RTEMS |
---|
73 | will access the appropriate files to map user and group Ids |
---|
74 | to names. |
---|
75 | |
---|
76 | If these files do not exist, then RTEMS will synthesize |
---|
77 | a minimal version so this family of services return without |
---|
78 | error. It is important to remember that a design goal of |
---|
79 | the RTEMS POSIX services is to provide useable and |
---|
80 | meaningful results even though a full process model |
---|
81 | is not available. |
---|
82 | |
---|
83 | @subsection Environment Variables |
---|
84 | |
---|
85 | POSIX allows for variables in the run-time environment. These are |
---|
86 | name/value pairs that make be dynamically set and obtained by |
---|
87 | programs. In a full POSIX environment with command line shell |
---|
88 | and multiple processes, environment variables may be set in |
---|
89 | one process -- such as the shell -- and inherited by child |
---|
90 | processes. In RTEMS, there is only one process and thus |
---|
91 | only one set of environment variables across all processes. |
---|
92 | |
---|
93 | |
---|
94 | @section Operations |
---|
95 | |
---|
96 | @subsection Accessing User and Group Ids |
---|
97 | |
---|
98 | The user Id associated with the current thread may be obtain |
---|
99 | using the @code{getuid()} service. Similarly, the group Id |
---|
100 | may be obtained using the @code{getgid()} service. |
---|
101 | |
---|
102 | @subsection Accessing Environment Variables |
---|
103 | |
---|
104 | The value associated with an environment variable may be |
---|
105 | obtained using the @code{getenv()} service and set using |
---|
106 | the @code{putenv()} service. |
---|
107 | |
---|
108 | @section Directives |
---|
109 | |
---|
110 | This section details the process environment manager's directives. |
---|
111 | A subsection is dedicated to each of this manager's directives |
---|
112 | and describes the calling sequence, related constants, usage, |
---|
113 | and status codes. |
---|
114 | |
---|
115 | @c |
---|
116 | @c |
---|
117 | @c |
---|
118 | @page |
---|
119 | @subsection getpid - Get Process ID |
---|
120 | |
---|
121 | @findex getpid |
---|
122 | @cindex get process id |
---|
123 | |
---|
124 | @subheading CALLING SEQUENCE: |
---|
125 | |
---|
126 | @ifset is-C |
---|
127 | @example |
---|
128 | int getpid( void ); |
---|
129 | @end example |
---|
130 | @end ifset |
---|
131 | |
---|
132 | @ifset is-Ada |
---|
133 | @end ifset |
---|
134 | |
---|
135 | @subheading STATUS CODES: |
---|
136 | |
---|
137 | The process Id is returned. |
---|
138 | |
---|
139 | @subheading DESCRIPTION: |
---|
140 | |
---|
141 | This service returns the process Id. |
---|
142 | |
---|
143 | @subheading NOTES: |
---|
144 | |
---|
145 | NONE |
---|
146 | |
---|
147 | @c |
---|
148 | @c |
---|
149 | @c |
---|
150 | @page |
---|
151 | @subsection getppid - Get Parent Process ID |
---|
152 | |
---|
153 | @findex getppid |
---|
154 | @cindex get parent process id |
---|
155 | |
---|
156 | @subheading CALLING SEQUENCE: |
---|
157 | |
---|
158 | @ifset is-C |
---|
159 | @example |
---|
160 | int getppid( void ); |
---|
161 | @end example |
---|
162 | @end ifset |
---|
163 | |
---|
164 | @ifset is-Ada |
---|
165 | @end ifset |
---|
166 | |
---|
167 | @subheading STATUS CODES: |
---|
168 | |
---|
169 | The parent process Id is returned. |
---|
170 | |
---|
171 | @subheading DESCRIPTION: |
---|
172 | |
---|
173 | This service returns the parent process Id. |
---|
174 | |
---|
175 | @subheading NOTES: |
---|
176 | |
---|
177 | NONE |
---|
178 | |
---|
179 | @c |
---|
180 | @c |
---|
181 | @c |
---|
182 | @page |
---|
183 | @subsection getuid - Get User ID |
---|
184 | |
---|
185 | @findex getuid |
---|
186 | @cindex get user id |
---|
187 | |
---|
188 | @subheading CALLING SEQUENCE: |
---|
189 | |
---|
190 | @ifset is-C |
---|
191 | @example |
---|
192 | int getuid( void ); |
---|
193 | @end example |
---|
194 | @end ifset |
---|
195 | |
---|
196 | @ifset is-Ada |
---|
197 | @end ifset |
---|
198 | |
---|
199 | @subheading STATUS CODES: |
---|
200 | |
---|
201 | The effective user Id is returned. |
---|
202 | |
---|
203 | @subheading DESCRIPTION: |
---|
204 | |
---|
205 | This service returns the effective user Id. |
---|
206 | |
---|
207 | @subheading NOTES: |
---|
208 | |
---|
209 | NONE |
---|
210 | |
---|
211 | @c |
---|
212 | @c |
---|
213 | @c |
---|
214 | @page |
---|
215 | @subsection geteuid - Get Effective User ID |
---|
216 | |
---|
217 | @findex geteuid |
---|
218 | @cindex get effective user id |
---|
219 | |
---|
220 | @subheading CALLING SEQUENCE: |
---|
221 | |
---|
222 | @ifset is-C |
---|
223 | @example |
---|
224 | int geteuid( void ); |
---|
225 | @end example |
---|
226 | @end ifset |
---|
227 | |
---|
228 | @ifset is-Ada |
---|
229 | @end ifset |
---|
230 | |
---|
231 | @subheading STATUS CODES: |
---|
232 | |
---|
233 | The effective group Id is returned. |
---|
234 | |
---|
235 | @subheading DESCRIPTION: |
---|
236 | |
---|
237 | This service returns the effective group Id. |
---|
238 | |
---|
239 | @subheading NOTES: |
---|
240 | |
---|
241 | NONE |
---|
242 | |
---|
243 | @c |
---|
244 | @c |
---|
245 | @c |
---|
246 | @page |
---|
247 | @subsection getgid - Get Real Group ID |
---|
248 | |
---|
249 | @findex getgid |
---|
250 | @cindex get real group id |
---|
251 | |
---|
252 | @subheading CALLING SEQUENCE: |
---|
253 | |
---|
254 | @ifset is-C |
---|
255 | @example |
---|
256 | int getgid( void ); |
---|
257 | @end example |
---|
258 | @end ifset |
---|
259 | |
---|
260 | @ifset is-Ada |
---|
261 | @end ifset |
---|
262 | |
---|
263 | @subheading STATUS CODES: |
---|
264 | |
---|
265 | The group Id is returned. |
---|
266 | |
---|
267 | @subheading DESCRIPTION: |
---|
268 | |
---|
269 | This service returns the group Id. |
---|
270 | |
---|
271 | @subheading NOTES: |
---|
272 | |
---|
273 | NONE |
---|
274 | |
---|
275 | @c |
---|
276 | @c |
---|
277 | @c |
---|
278 | @page |
---|
279 | @subsection getegid - Get Effective Group ID |
---|
280 | |
---|
281 | @findex getegid |
---|
282 | @cindex get effective group id |
---|
283 | |
---|
284 | @subheading CALLING SEQUENCE: |
---|
285 | |
---|
286 | @ifset is-C |
---|
287 | @example |
---|
288 | int getegid( void ); |
---|
289 | @end example |
---|
290 | @end ifset |
---|
291 | |
---|
292 | @ifset is-Ada |
---|
293 | @end ifset |
---|
294 | |
---|
295 | @subheading STATUS CODES: |
---|
296 | |
---|
297 | The effective group Id is returned. |
---|
298 | |
---|
299 | @subheading DESCRIPTION: |
---|
300 | |
---|
301 | This service returns the effective group Id. |
---|
302 | |
---|
303 | @subheading NOTES: |
---|
304 | |
---|
305 | NONE |
---|
306 | |
---|
307 | @c |
---|
308 | @c |
---|
309 | @c |
---|
310 | @page |
---|
311 | @subsection setuid - Set User ID |
---|
312 | |
---|
313 | @findex setuid |
---|
314 | @cindex set user id |
---|
315 | |
---|
316 | @subheading CALLING SEQUENCE: |
---|
317 | |
---|
318 | @ifset is-C |
---|
319 | @example |
---|
320 | int setuid( |
---|
321 | uid_t uid |
---|
322 | ); |
---|
323 | @end example |
---|
324 | @end ifset |
---|
325 | |
---|
326 | @ifset is-Ada |
---|
327 | @end ifset |
---|
328 | |
---|
329 | @subheading STATUS CODES: |
---|
330 | |
---|
331 | This service returns 0. |
---|
332 | |
---|
333 | @subheading DESCRIPTION: |
---|
334 | |
---|
335 | This service sets the user Id to @code{uid}. |
---|
336 | |
---|
337 | @subheading NOTES: |
---|
338 | |
---|
339 | NONE |
---|
340 | |
---|
341 | @c |
---|
342 | @c |
---|
343 | @c |
---|
344 | @page |
---|
345 | @subsection setgid - Set Group ID |
---|
346 | |
---|
347 | @findex setgid |
---|
348 | @cindex set group id |
---|
349 | |
---|
350 | @subheading CALLING SEQUENCE: |
---|
351 | |
---|
352 | @ifset is-C |
---|
353 | @example |
---|
354 | int setgid( |
---|
355 | gid_t gid |
---|
356 | ); |
---|
357 | @end example |
---|
358 | @end ifset |
---|
359 | |
---|
360 | @ifset is-Ada |
---|
361 | @end ifset |
---|
362 | |
---|
363 | @subheading STATUS CODES: |
---|
364 | |
---|
365 | This service returns 0. |
---|
366 | |
---|
367 | @subheading DESCRIPTION: |
---|
368 | |
---|
369 | This service sets the group Id to @code{gid}. |
---|
370 | |
---|
371 | @subheading NOTES: |
---|
372 | |
---|
373 | NONE |
---|
374 | |
---|
375 | @c |
---|
376 | @c |
---|
377 | @c |
---|
378 | @page |
---|
379 | @subsection getgroups - Get Supplementary Group IDs |
---|
380 | |
---|
381 | @findex getgroups |
---|
382 | @cindex get supplementary group ids |
---|
383 | |
---|
384 | @subheading CALLING SEQUENCE: |
---|
385 | |
---|
386 | @ifset is-C |
---|
387 | @example |
---|
388 | int getgroups( |
---|
389 | int gidsetsize, |
---|
390 | gid_t grouplist[] |
---|
391 | ); |
---|
392 | @end example |
---|
393 | @end ifset |
---|
394 | |
---|
395 | @ifset is-Ada |
---|
396 | @end ifset |
---|
397 | |
---|
398 | @subheading STATUS CODES: |
---|
399 | |
---|
400 | NA |
---|
401 | |
---|
402 | @subheading DESCRIPTION: |
---|
403 | |
---|
404 | This service is not implemented as RTEMS has no notion of |
---|
405 | supplemental groups. |
---|
406 | |
---|
407 | @subheading NOTES: |
---|
408 | |
---|
409 | If supported, this routine would only be allowed for |
---|
410 | the super-user. |
---|
411 | |
---|
412 | @c |
---|
413 | @c |
---|
414 | @c |
---|
415 | @page |
---|
416 | @subsection getlogin - Get User Name |
---|
417 | |
---|
418 | @findex getlogin |
---|
419 | @cindex get user name |
---|
420 | |
---|
421 | @subheading CALLING SEQUENCE: |
---|
422 | |
---|
423 | @ifset is-C |
---|
424 | @example |
---|
425 | char *getlogin( void ); |
---|
426 | @end example |
---|
427 | @end ifset |
---|
428 | |
---|
429 | @ifset is-Ada |
---|
430 | @end ifset |
---|
431 | |
---|
432 | @subheading STATUS CODES: |
---|
433 | |
---|
434 | Returns a pointer to a string containing the name of the |
---|
435 | current user. |
---|
436 | |
---|
437 | @subheading DESCRIPTION: |
---|
438 | |
---|
439 | This routine returns the name of the current user. |
---|
440 | |
---|
441 | @subheading NOTES: |
---|
442 | |
---|
443 | This routine is not reentrant and subsequent calls to |
---|
444 | @code{getlogin()} will overwrite the same buffer. |
---|
445 | |
---|
446 | @c |
---|
447 | @c |
---|
448 | @c |
---|
449 | @page |
---|
450 | @subsection getlogin_r - Reentrant Get User Name |
---|
451 | |
---|
452 | @findex getlogin_r |
---|
453 | @cindex reentrant get user name |
---|
454 | @cindex get user name, reentrant |
---|
455 | |
---|
456 | @subheading CALLING SEQUENCE: |
---|
457 | |
---|
458 | @ifset is-C |
---|
459 | @example |
---|
460 | int getlogin_r( |
---|
461 | char *name, |
---|
462 | size_t namesize |
---|
463 | ); |
---|
464 | @end example |
---|
465 | @end ifset |
---|
466 | |
---|
467 | @ifset is-Ada |
---|
468 | @end ifset |
---|
469 | |
---|
470 | @subheading STATUS CODES: |
---|
471 | |
---|
472 | @table @b |
---|
473 | @item EINVAL |
---|
474 | The arguments were invalid. |
---|
475 | |
---|
476 | @end table |
---|
477 | |
---|
478 | @subheading DESCRIPTION: |
---|
479 | |
---|
480 | This is a reentrant version of the @code{getlogin()} service. The |
---|
481 | caller specified their own buffer, @code{name}, as well as the |
---|
482 | length of this buffer, @code{namesize}. |
---|
483 | |
---|
484 | @subheading NOTES: |
---|
485 | |
---|
486 | NONE |
---|
487 | |
---|
488 | @c |
---|
489 | @c |
---|
490 | @c |
---|
491 | @page |
---|
492 | @subsection getpgrp - Get Process Group ID |
---|
493 | |
---|
494 | @findex getpgrp |
---|
495 | @cindex get process group id |
---|
496 | |
---|
497 | @subheading CALLING SEQUENCE: |
---|
498 | |
---|
499 | @ifset is-C |
---|
500 | @example |
---|
501 | pid_t getpgrp( void ); |
---|
502 | @end example |
---|
503 | @end ifset |
---|
504 | |
---|
505 | @ifset is-Ada |
---|
506 | @end ifset |
---|
507 | |
---|
508 | @subheading STATUS CODES: |
---|
509 | |
---|
510 | The procress group Id is returned. |
---|
511 | |
---|
512 | @subheading DESCRIPTION: |
---|
513 | |
---|
514 | This service returns the current progress group Id. |
---|
515 | |
---|
516 | @subheading NOTES: |
---|
517 | |
---|
518 | This routine is implemented in a somewhat meaningful |
---|
519 | way for RTEMS but is truly not functional. |
---|
520 | |
---|
521 | @c |
---|
522 | @c |
---|
523 | @c |
---|
524 | @page |
---|
525 | @subsection setsid - Create Session and Set Process Group ID |
---|
526 | |
---|
527 | @findex setsid |
---|
528 | @cindex create session and set process group id |
---|
529 | |
---|
530 | @subheading CALLING SEQUENCE: |
---|
531 | |
---|
532 | @ifset is-C |
---|
533 | @example |
---|
534 | pid_t setsid( void ); |
---|
535 | @end example |
---|
536 | @end ifset |
---|
537 | |
---|
538 | @ifset is-Ada |
---|
539 | @end ifset |
---|
540 | |
---|
541 | @subheading STATUS CODES: |
---|
542 | |
---|
543 | @table @b |
---|
544 | @item EPERM |
---|
545 | The application does not have permission to create a process group. |
---|
546 | |
---|
547 | @end table |
---|
548 | |
---|
549 | @subheading DESCRIPTION: |
---|
550 | |
---|
551 | This routine always returns @code{EPERM} as RTEMS has no way |
---|
552 | to create new processes and thus no way to create a new process |
---|
553 | group. |
---|
554 | |
---|
555 | @subheading NOTES: |
---|
556 | |
---|
557 | NONE |
---|
558 | |
---|
559 | @c |
---|
560 | @c |
---|
561 | @c |
---|
562 | @page |
---|
563 | @subsection setpgid - Set Process Group ID for Job Control |
---|
564 | |
---|
565 | @findex setpgid |
---|
566 | @cindex set process group id for job control |
---|
567 | |
---|
568 | @subheading CALLING SEQUENCE: |
---|
569 | |
---|
570 | @ifset is-C |
---|
571 | @example |
---|
572 | int setpgid( |
---|
573 | pid_t pid, |
---|
574 | pid_t pgid |
---|
575 | ); |
---|
576 | @end example |
---|
577 | @end ifset |
---|
578 | |
---|
579 | @ifset is-Ada |
---|
580 | @end ifset |
---|
581 | |
---|
582 | @subheading STATUS CODES: |
---|
583 | |
---|
584 | @table @b |
---|
585 | @item ENOSYS |
---|
586 | The routine is not implemented. |
---|
587 | |
---|
588 | @end table |
---|
589 | |
---|
590 | @subheading DESCRIPTION: |
---|
591 | |
---|
592 | This service is not implemented for RTEMS as process groups are not |
---|
593 | supported. |
---|
594 | |
---|
595 | @subheading NOTES: |
---|
596 | |
---|
597 | NONE |
---|
598 | |
---|
599 | @c |
---|
600 | @c |
---|
601 | @c |
---|
602 | @page |
---|
603 | @subsection uname - Get System Name |
---|
604 | |
---|
605 | @findex uname |
---|
606 | @cindex get system name |
---|
607 | |
---|
608 | @subheading CALLING SEQUENCE: |
---|
609 | |
---|
610 | @ifset is-C |
---|
611 | @example |
---|
612 | int uname( |
---|
613 | struct utsname *name |
---|
614 | ); |
---|
615 | @end example |
---|
616 | @end ifset |
---|
617 | |
---|
618 | @ifset is-Ada |
---|
619 | @end ifset |
---|
620 | |
---|
621 | @subheading STATUS CODES: |
---|
622 | |
---|
623 | @table @b |
---|
624 | @item EPERM |
---|
625 | The provided structure pointer is invalid. |
---|
626 | |
---|
627 | @end table |
---|
628 | |
---|
629 | @subheading DESCRIPTION: |
---|
630 | |
---|
631 | This service returns system information to the caller. It does this |
---|
632 | by filling in the @code{struct utsname} format structure for the |
---|
633 | caller. |
---|
634 | |
---|
635 | @subheading NOTES: |
---|
636 | |
---|
637 | The information provided includes the operating system (RTEMS in |
---|
638 | all configurations), the node number, the release as the RTEMS |
---|
639 | version, and the CPU family and model. The CPU model name |
---|
640 | will indicate the multilib executive variant being used. |
---|
641 | |
---|
642 | @c |
---|
643 | @c |
---|
644 | @c |
---|
645 | @page |
---|
646 | @subsection times - Get process times |
---|
647 | |
---|
648 | @findex times |
---|
649 | @cindex get process times |
---|
650 | |
---|
651 | @subheading CALLING SEQUENCE: |
---|
652 | |
---|
653 | @example |
---|
654 | #include <sys/time.h> |
---|
655 | |
---|
656 | clock_t times( |
---|
657 | struct tms *ptms |
---|
658 | ); |
---|
659 | @end example |
---|
660 | |
---|
661 | @subheading STATUS CODES: |
---|
662 | |
---|
663 | This routine returns the number of clock ticks that have elapsed |
---|
664 | since the system was initialized (e.g. the application was |
---|
665 | started). |
---|
666 | |
---|
667 | @subheading DESCRIPTION: |
---|
668 | |
---|
669 | @code{times} stores the current process times in @code{ptms}. The |
---|
670 | format of @code{struct tms} is as defined in |
---|
671 | @code{<sys/times.h>}. RTEMS fills in the field @code{tms_utime} |
---|
672 | with the number of ticks that the calling thread has executed |
---|
673 | and the field @code{tms_stime} with the number of clock ticks |
---|
674 | since system boot (also returned). All other fields in the |
---|
675 | @code{ptms} are left zero. |
---|
676 | |
---|
677 | @subheading NOTES: |
---|
678 | |
---|
679 | RTEMS has no way to distinguish between user and system time |
---|
680 | so this routine returns the most meaningful information |
---|
681 | possible. |
---|
682 | |
---|
683 | @c |
---|
684 | @c |
---|
685 | @c |
---|
686 | @page |
---|
687 | @subsection getenv - Get Environment Variables |
---|
688 | |
---|
689 | @findex getenv |
---|
690 | @cindex get environment variables |
---|
691 | |
---|
692 | @subheading CALLING SEQUENCE: |
---|
693 | |
---|
694 | @ifset is-C |
---|
695 | @example |
---|
696 | char *getenv( |
---|
697 | const char *name |
---|
698 | ); |
---|
699 | @end example |
---|
700 | @end ifset |
---|
701 | |
---|
702 | @ifset is-Ada |
---|
703 | @end ifset |
---|
704 | |
---|
705 | @subheading STATUS CODES: |
---|
706 | |
---|
707 | @table @b |
---|
708 | @item NULL |
---|
709 | when no match |
---|
710 | |
---|
711 | @item pointer to value |
---|
712 | when successful |
---|
713 | |
---|
714 | @end table |
---|
715 | |
---|
716 | @subheading DESCRIPTION: |
---|
717 | |
---|
718 | This service searches the set of environment variables for |
---|
719 | a string that matches the specified @code{name}. If found, |
---|
720 | it returns the associated value. |
---|
721 | |
---|
722 | @subheading NOTES: |
---|
723 | |
---|
724 | The environment list consists of name value pairs that |
---|
725 | are of the form @i{name = value}. |
---|
726 | |
---|
727 | @c |
---|
728 | @c |
---|
729 | @c |
---|
730 | @page |
---|
731 | @subsection setenv - Set Environment Variables |
---|
732 | |
---|
733 | @findex setenv |
---|
734 | @cindex set environment variables |
---|
735 | |
---|
736 | @subheading CALLING SEQUENCE: |
---|
737 | |
---|
738 | @ifset is-C |
---|
739 | @example |
---|
740 | int setenv( |
---|
741 | const char *name, |
---|
742 | const char *value, |
---|
743 | int overwrite |
---|
744 | ); |
---|
745 | @end example |
---|
746 | @end ifset |
---|
747 | |
---|
748 | @ifset is-Ada |
---|
749 | @end ifset |
---|
750 | |
---|
751 | @subheading STATUS CODES: |
---|
752 | |
---|
753 | Returns 0 if successful and -1 otherwise. |
---|
754 | |
---|
755 | @subheading DESCRIPTION: |
---|
756 | |
---|
757 | This service adds the variable @code{name} to the environment with |
---|
758 | @code{value}. If @code{name} is not already exist, then it is |
---|
759 | created. If @code{name} exists and @code{overwrite} is zero, then |
---|
760 | the previous value is not overwritten. |
---|
761 | |
---|
762 | @subheading NOTES: |
---|
763 | |
---|
764 | NONE |
---|
765 | |
---|
766 | @c |
---|
767 | @c |
---|
768 | @c |
---|
769 | @page |
---|
770 | @subsection ctermid - Generate Terminal Pathname |
---|
771 | |
---|
772 | @findex ctermid |
---|
773 | @cindex generate terminal pathname |
---|
774 | |
---|
775 | @subheading CALLING SEQUENCE: |
---|
776 | |
---|
777 | @ifset is-C |
---|
778 | @example |
---|
779 | char *ctermid( |
---|
780 | char *s |
---|
781 | ); |
---|
782 | @end example |
---|
783 | @end ifset |
---|
784 | |
---|
785 | @ifset is-Ada |
---|
786 | @end ifset |
---|
787 | |
---|
788 | @subheading STATUS CODES: |
---|
789 | |
---|
790 | Returns a pointer to a string indicating the pathname for the controlling |
---|
791 | terminal. |
---|
792 | |
---|
793 | @subheading DESCRIPTION: |
---|
794 | |
---|
795 | This service returns the name of the terminal device associated with |
---|
796 | this process. If @code{s} is NULL, then a pointer to a static buffer |
---|
797 | is returned. Otherwise, @code{s} is assumed to have a buffer of |
---|
798 | sufficient size to contain the name of the controlling terminal. |
---|
799 | |
---|
800 | @subheading NOTES: |
---|
801 | |
---|
802 | By default on RTEMS systems, the controlling terminal is @code{/dev/console}. |
---|
803 | Again this implementation is of limited meaning, but it provides |
---|
804 | true and useful results which should be sufficient to ease porting |
---|
805 | applications from a full POSIX implementation to the reduced |
---|
806 | profile supported by RTEMS. |
---|
807 | |
---|
808 | @c |
---|
809 | @c |
---|
810 | @c |
---|
811 | @page |
---|
812 | @subsection ttyname - Determine Terminal Device Name |
---|
813 | |
---|
814 | @findex ttyname |
---|
815 | @cindex determine terminal device name |
---|
816 | |
---|
817 | @subheading CALLING SEQUENCE: |
---|
818 | |
---|
819 | @ifset is-C |
---|
820 | @example |
---|
821 | char *ttyname( |
---|
822 | int fd |
---|
823 | ); |
---|
824 | @end example |
---|
825 | @end ifset |
---|
826 | |
---|
827 | @ifset is-Ada |
---|
828 | @end ifset |
---|
829 | |
---|
830 | @subheading STATUS CODES: |
---|
831 | |
---|
832 | Pointer to a string containing the terminal device name or |
---|
833 | NULL is returned on any error. |
---|
834 | |
---|
835 | @subheading DESCRIPTION: |
---|
836 | |
---|
837 | This service returns a pointer to the pathname of the terminal |
---|
838 | device that is open on the file descriptor @code{fd}. If |
---|
839 | @code{fd} is not a valid descriptor for a terminal device, |
---|
840 | then NULL is returned. |
---|
841 | |
---|
842 | @subheading NOTES: |
---|
843 | |
---|
844 | This routine uses a static buffer. |
---|
845 | |
---|
846 | @c |
---|
847 | @c |
---|
848 | @c |
---|
849 | @page |
---|
850 | @subsection ttyname_r - Reentrant Determine Terminal Device Name |
---|
851 | |
---|
852 | @findex ttyname_r |
---|
853 | @cindex reentrant determine terminal device name |
---|
854 | |
---|
855 | @subheading CALLING SEQUENCE: |
---|
856 | |
---|
857 | @ifset is-C |
---|
858 | @example |
---|
859 | int ttyname_r( |
---|
860 | int fd, |
---|
861 | char *name, |
---|
862 | int namesize |
---|
863 | ); |
---|
864 | @end example |
---|
865 | @end ifset |
---|
866 | |
---|
867 | @ifset is-Ada |
---|
868 | @end ifset |
---|
869 | |
---|
870 | @subheading STATUS CODES: |
---|
871 | |
---|
872 | This routine returns -1 and sets @code{errno} as follows: |
---|
873 | |
---|
874 | @table @b |
---|
875 | @item EBADF |
---|
876 | If not a valid descriptor for a terminal device. |
---|
877 | |
---|
878 | @item EINVAL |
---|
879 | If @code{name} is NULL or @code{namesize} are insufficient. |
---|
880 | |
---|
881 | @end table |
---|
882 | |
---|
883 | @subheading DESCRIPTION: |
---|
884 | |
---|
885 | This service the pathname of the terminal device that is open |
---|
886 | on the file descriptor @code{fd}. |
---|
887 | |
---|
888 | @subheading NOTES: |
---|
889 | |
---|
890 | NONE |
---|
891 | |
---|
892 | @c |
---|
893 | @c |
---|
894 | @c |
---|
895 | @page |
---|
896 | @subsection isatty - Determine if File Descriptor is Terminal |
---|
897 | |
---|
898 | @findex isatty |
---|
899 | @cindex determine if file descriptor is terminal |
---|
900 | |
---|
901 | @subheading CALLING SEQUENCE: |
---|
902 | |
---|
903 | @ifset is-C |
---|
904 | @example |
---|
905 | int isatty( |
---|
906 | int fd |
---|
907 | ); |
---|
908 | @end example |
---|
909 | @end ifset |
---|
910 | |
---|
911 | @ifset is-Ada |
---|
912 | @end ifset |
---|
913 | |
---|
914 | @subheading STATUS CODES: |
---|
915 | |
---|
916 | Returns 1 if @code{fd} is a terminal device and 0 otherwise. |
---|
917 | |
---|
918 | @subheading DESCRIPTION: |
---|
919 | |
---|
920 | This service returns 1 if @code{fd} is an open file descriptor |
---|
921 | connected to a terminal and 0 otherwise. |
---|
922 | |
---|
923 | @subheading NOTES: |
---|
924 | |
---|
925 | @c |
---|
926 | @c |
---|
927 | @c |
---|
928 | @page |
---|
929 | @subsection sysconf - Get Configurable System Variables |
---|
930 | |
---|
931 | @findex sysconf |
---|
932 | @cindex get configurable system variables |
---|
933 | |
---|
934 | @subheading CALLING SEQUENCE: |
---|
935 | |
---|
936 | @ifset is-C |
---|
937 | @example |
---|
938 | long sysconf( |
---|
939 | int name |
---|
940 | ); |
---|
941 | @end example |
---|
942 | @end ifset |
---|
943 | |
---|
944 | @ifset is-Ada |
---|
945 | @end ifset |
---|
946 | |
---|
947 | @subheading STATUS CODES: |
---|
948 | |
---|
949 | The value returned is the actual value of the system resource. |
---|
950 | If the requested configuration name is a feature flag, then |
---|
951 | 1 is returned if the available and 0 if it is not. On any |
---|
952 | other error condition, -1 is returned. |
---|
953 | |
---|
954 | @subheading DESCRIPTION: |
---|
955 | |
---|
956 | This service is the mechanism by which an application determines |
---|
957 | values for system limits or options at runtime. |
---|
958 | |
---|
959 | @subheading NOTES: |
---|
960 | |
---|
961 | Much of the information that may be obtained via @code{sysconf} |
---|
962 | has equivalent macros in @code{<unistd.h}. However, those |
---|
963 | macros reflect conservative limits which may have been altered |
---|
964 | by application configuration. |
---|