1UnixLabels(3) OCaml library UnixLabels(3)
2
6 UnixLabels - Interface to the Unix system.
7
9 Module UnixLabels
10
12 Module UnixLabels
13 : sig end
14 Interface to the Unix system. To use as replacement to default Unix
17 module, add module Unix = UnixLabels in your implementation.
18 Error report
26 type error = Unix.error =
27 | E2BIG (* Argument list too long
28 *)
29 | EACCES (* Permission denied
30 *)
31 | EAGAIN (* Resource temporarily unavailable; try again
32 *)
33 | EBADF (* Bad file descriptor
34 *)
35 | EBUSY (* Resource unavailable
36 *)
37 | ECHILD (* No child process
38 *)
39 | EDEADLK (* Resource deadlock would occur
40 *)
41 | EDOM (* Domain error for math functions, etc.
42 *)
43 | EEXIST (* File exists
44 *)
45 | EFAULT (* Bad address
46 *)
47 | EFBIG (* File too large
48 *)
49 | EINTR (* Function interrupted by signal
50 *)
51 | EINVAL (* Invalid argument
52 *)
53 | EIO (* Hardware I/O error
54 *)
55 | EISDIR (* Is a directory
56 *)
57 | EMFILE (* Too many open files by the process
58 *)
59 | EMLINK (* Too many links
60 *)
61 | ENAMETOOLONG (* Filename too long
62 *)
63 | ENFILE (* Too many open files in the system
64 *)
65 | ENODEV (* No such device
66 *)
67 | ENOENT (* No such file or directory
68 *)
69 | ENOEXEC (* Not an executable file
70 *)
71 | ENOLCK (* No locks available
72 *)
73 | ENOMEM (* Not enough memory
74 *)
75 | ENOSPC (* No space left on device
76 *)
77 | ENOSYS (* Function not supported
78 *)
79 | ENOTDIR (* Not a directory
80 *)
81 | ENOTEMPTY (* Directory not empty
82 *)
83 | ENOTTY (* Inappropriate I/O control operation
84 *)
85 | ENXIO (* No such device or address
86 *)
87 | EPERM (* Operation not permitted
88 *)
89 | EPIPE (* Broken pipe
90 *)
91 | ERANGE (* Result too large
92 *)
93 | EROFS (* Read-only file system
94 *)
95 | ESPIPE (* Invalid seek e.g. on a pipe
96 *)
97 | ESRCH (* No such process
98 *)
99 | EXDEV (* Invalid link
100 *)
101 | EWOULDBLOCK (* Operation would block
102 *)
103 | EINPROGRESS (* Operation now in progress
104 *)
105 | EALREADY (* Operation already in progress
106 *)
107 | ENOTSOCK (* Socket operation on non-socket
108 *)
109 | EDESTADDRREQ (* Destination address required
110 *)
111 | EMSGSIZE (* Message too long
112 *)
113 | EPROTOTYPE (* Protocol wrong type for socket
114 *)
115 | ENOPROTOOPT (* Protocol not available
116 *)
117 | EPROTONOSUPPORT (* Protocol not supported
118 *)
119 | ESOCKTNOSUPPORT (* Socket type not supported
120 *)
121 | EOPNOTSUPP (* Operation not supported on socket
122 *)
123 | EPFNOSUPPORT (* Protocol family not supported
124 *)
125 | EAFNOSUPPORT (* Address family not supported by protocol family
126 *)
127 | EADDRINUSE (* Address already in use
128 *)
129 | EADDRNOTAVAIL (* Can't assign requested address
130 *)
131 | ENETDOWN (* Network is down
132 *)
133 | ENETUNREACH (* Network is unreachable
134 *)
135 | ENETRESET (* Network dropped connection on reset
136 *)
137 | ECONNABORTED (* Software caused connection abort
138 *)
139 | ECONNRESET (* Connection reset by peer
140 *)
141 | ENOBUFS (* No buffer space available
142 *)
143 | EISCONN (* Socket is already connected
144 *)
145 | ENOTCONN (* Socket is not connected
146 *)
147 | ESHUTDOWN (* Can't send after socket shutdown
148 *)
149 | ETOOMANYREFS (* Too many references: can't splice
150 *)
151 | ETIMEDOUT (* Connection timed out
152 *)
153 | ECONNREFUSED (* Connection refused
154 *)
155 | EHOSTDOWN (* Host is down
156 *)
157 | EHOSTUNREACH (* No route to host
158 *)
159 | ELOOP (* Too many levels of symbolic links
160 *)
161 | EOVERFLOW (* File size or position not representable
162 *)
163 | EUNKNOWNERR of int
164 (* Unknown error
165 *)
166 The type of error codes. Errors defined in the POSIX standard and
169 additional errors from UNIX98 and BSD. All other errors are mapped to
170 EUNKNOWNERR.
171 exception Unix_error of error * string * string
175 Raised by the system calls below when an error is encountered. The
178 first component is the error code; the second component is the function
179 name; the third component is the string parameter to the function, if
180 it has one, or the empty string otherwise.
181 val error_message : error -> string
185 Return a string describing the given error code.
187 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
191 handle_unix_error f x applies f to x and returns the result. If the
194 exception Unix_error is raised, it prints a message describing the
195 error and exits with code 2.
196 Access to the process environment
201 val environment : unit -> string array
202 Return the process environment, as an array of strings with the format
204 ``variable=value''.
205 val getenv : string -> string
209 Return the value associated to a variable in the process environment.
211 Raise Not_found if the variable is unbound. (This function is identi‐
212 cal to Sys.getenv .)
213 val unsafe_getenv : string -> string
217 Return the value associated to a variable in the process environment.
219 Unlike UnixLabels.getenv , this function returns the value even if the
221 process has special privileges. It is considered unsafe because the
222 programmer of a setuid or setgid program must be careful to avoid using
223 maliciously crafted environment variables in the search path for exe‐
224 cutables, the locations for temporary files or logs, and the like.
225 Since 4.06.0
228 Raises Not_found if the variable is unbound.
231 val putenv : string -> string -> unit
235 Unix.putenv name value sets the value associated to a variable in the
238 process environment. name is the name of the environment variable, and
239 value its new associated value.
240 Process handling
245 type process_status = Unix.process_status =
246 | WEXITED of int
247 (* The process terminated normally by exit ; the argument is the
248 return code.
249 *)
250 | WSIGNALED of int
251 (* The process was killed by a signal; the argument is the signal
252 number.
253 *)
254 | WSTOPPED of int
255 (* The process was stopped by a signal; the argument is the signal
256 number.
257 *)
258 The termination status of a process. See module Sys for the defini‐
261 tions of the standard signal numbers. Note that they are not the num‐
262 bers used by the OS.
263 type wait_flag = Unix.wait_flag =
266 | WNOHANG (* do not block if no child has died yet, but immediately
267 return with a pid equal to 0.
268 *)
269 | WUNTRACED (* report also the children that receive stop signals.
270 *)
271 Flags for UnixLabels.waitpid .
274 val execv : prog:string -> args:string array -> 'a
278 execv prog args execute the program in file prog , with the arguments
281 args , and the current process environment. These execv* functions
282 never return: on success, the current program is replaced by the new
283 one; on failure, a UnixLabels.Unix_error exception is raised.
284 val execve : prog:string -> args:string array -> env:string array -> 'a
288 Same as UnixLabels.execv , except that the third argument provides the
290 environment to the program executed.
291 val execvp : prog:string -> args:string array -> 'a
295 Same as UnixLabels.execv , except that the program is searched in the
297 path.
298 val execvpe : prog:string -> args:string array -> env:string array ->
302 'a
303 Same as UnixLabels.execve , except that the program is searched in the
305 path.
306 val fork : unit -> int
310 Fork a new process. The returned integer is 0 for the child process,
312 the pid of the child process for the parent process.
313 val wait : unit -> int * process_status
317 Wait until one of the children processes die, and return its pid and
319 termination status.
320 val waitpid : mode:wait_flag list -> int -> int * process_status
324 Same as UnixLabels.wait , but waits for the child process whose pid is
326 given. A pid of -1 means wait for any child. A pid of 0 means wait
327 for any child in the same process group as the current process. Nega‐
328 tive pid arguments represent process groups. The list of options indi‐
329 cates whether waitpid should return immediately without waiting, or
330 also report stopped children.
331 val system : string -> process_status
335 Execute the given command, wait until it terminates, and return its
337 termination status. The string is interpreted by the shell /bin/sh and
338 therefore can contain redirections, quotes, variables, etc. The result
339 WEXITED 127 indicates that the shell couldn't be executed.
340 val getpid : unit -> int
344 Return the pid of the process.
346 val getppid : unit -> int
350 Return the pid of the parent process.
352 val nice : int -> int
356 Change the process priority. The integer argument is added to the
358 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
359 ties.) Return the new nice value.
360 Basic file input/output
365 type file_descr = Unix.file_descr
366 The abstract type of file descriptors.
369 val stdin : file_descr
373 File descriptor for standard input.
375 val stdout : file_descr
379 File descriptor for standard output.
381 val stderr : file_descr
385 File descriptor for standard error.
387 type open_flag = Unix.open_flag =
390 | O_RDONLY (* Open for reading
391 *)
392 | O_WRONLY (* Open for writing
393 *)
394 | O_RDWR (* Open for reading and writing
395 *)
396 | O_NONBLOCK (* Open in non-blocking mode
397 *)
398 | O_APPEND (* Open for append
399 *)
400 | O_CREAT (* Create if nonexistent
401 *)
402 | O_TRUNC (* Truncate to 0 length if existing
403 *)
404 | O_EXCL (* Fail if existing
405 *)
406 | O_NOCTTY (* Don't make this dev a controlling tty
407 *)
408 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
409 pletion'
410 *)
411 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
412 pletion'
413 *)
414 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
415 *)
416 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
417 still open
418 *)
419 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
420 by UnixLabels.openfile
421 *)
423 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
424 default.
425 *)
426 The flags to UnixLabels.openfile .
429 type file_perm = int
432 The type of file access rights, e.g. 0o640 is read and write for user,
435 read for group, none for others
436 val openfile : string -> mode:open_flag list -> perm:file_perm ->
440 file_descr
441 Open the named file with the given flags. Third argument is the permis‐
443 sions to give to the file if it is created. Return a file descriptor on
444 the named file.
445 val close : file_descr -> unit
449 Close a file descriptor.
451 val read : file_descr -> buf:bytes -> pos:int -> len:int -> int
455 read fd buff ofs len reads len bytes from descriptor fd , storing them
458 in byte sequence buff , starting at position ofs in buff . Return the
459 number of bytes actually read.
460 val write : file_descr -> buf:bytes -> pos:int -> len:int -> int
464 write fd buff ofs len writes len bytes to descriptor fd , taking them
467 from byte sequence buff , starting at position ofs in buff . Return the
468 number of bytes actually written. write repeats the writing operation
469 until all bytes have been written or an error occurs.
470 val single_write : file_descr -> buf:bytes -> pos:int -> len:int -> int
474 Same as write , but attempts to write only once. Thus, if an error
476 occurs, single_write guarantees that no data has been written.
477 val write_substring : file_descr -> buf:string -> pos:int -> len:int ->
481 int
482 Same as write , but take the data from a string instead of a byte
484 sequence.
485 Since 4.02.0
488 val single_write_substring : file_descr -> buf:string -> pos:int ->
492 len:int -> int
493 Same as single_write , but take the data from a string instead of a
495 byte sequence.
496 Since 4.02.0
499 Interfacing with the standard input/output library
504 val in_channel_of_descr : file_descr -> in_channel
505 Create an input channel reading from the given descriptor. The channel
507 is initially in binary mode; use set_binary_mode_in ic false if text
508 mode is desired.
509 val out_channel_of_descr : file_descr -> out_channel
513 Create an output channel writing on the given descriptor. The channel
515 is initially in binary mode; use set_binary_mode_out oc false if text
516 mode is desired.
517 val descr_of_in_channel : in_channel -> file_descr
521 Return the descriptor corresponding to an input channel.
523 val descr_of_out_channel : out_channel -> file_descr
527 Return the descriptor corresponding to an output channel.
529 Seeking and truncating
534 type seek_command = Unix.seek_command =
535 | SEEK_SET (* indicates positions relative to the beginning of the
536 file
537 *)
538 | SEEK_CUR (* indicates positions relative to the current position
539 *)
540 | SEEK_END (* indicates positions relative to the end of the file
541 *)
542 Positioning modes for UnixLabels.lseek .
545 val lseek : file_descr -> int -> mode:seek_command -> int
549 Set the current position for a file descriptor, and return the result‐
551 ing offset (from the beginning of the file).
552 val truncate : string -> len:int -> unit
556 Truncates the named file to the given size.
558 val ftruncate : file_descr -> len:int -> unit
562 Truncates the file corresponding to the given descriptor to the given
564 size.
565 File status
570 type file_kind = Unix.file_kind =
571 | S_REG (* Regular file
572 *)
573 | S_DIR (* Directory
574 *)
575 | S_CHR (* Character device
576 *)
577 | S_BLK (* Block device
578 *)
579 | S_LNK (* Symbolic link
580 *)
581 | S_FIFO (* Named pipe
582 *)
583 | S_SOCK (* Socket
584 *)
585 type stats = Unix.stats = {
590 st_dev : int ; (* Device number
591 *)
592 st_ino : int ; (* Inode number
593 *)
594 st_kind : file_kind ; (* Kind of the file
595 *)
596 st_perm : file_perm ; (* Access rights
597 *)
598 st_nlink : int ; (* Number of links
599 *)
600 st_uid : int ; (* User id of the owner
601 *)
602 st_gid : int ; (* Group ID of the file's group
603 *)
604 st_rdev : int ; (* Device ID (if special file)
605 *)
606 st_size : int ; (* Size in bytes
607 *)
608 st_atime : float ; (* Last access time
609 *)
610 st_mtime : float ; (* Last modification time
611 *)
612 st_ctime : float ; (* Last status change time
613 *)
614 }
615 The information returned by the UnixLabels.stat calls.
618 val stat : string -> stats
622 Return the information for the named file.
624 val lstat : string -> stats
628 Same as UnixLabels.stat , but in case the file is a symbolic link,
630 return the information for the link itself.
631 val fstat : file_descr -> stats
635 Return the information for the file associated with the given descrip‐
637 tor.
638 val isatty : file_descr -> bool
642 Return true if the given file descriptor refers to a terminal or con‐
644 sole window, false otherwise.
645 File operations on large files
650 module LargeFile : sig end
651 File operations on large files. This sub-module provides 64-bit vari‐
654 ants of the functions UnixLabels.lseek (for positioning a file descrip‐
655 tor), UnixLabels.truncate and UnixLabels.ftruncate (for changing the
656 size of a file), and UnixLabels.stat , UnixLabels.lstat and UnixLa‐
657 bels.fstat (for obtaining information on files). These alternate func‐
658 tions represent positions and sizes by 64-bit integers (type int64 )
659 instead of regular integers (type int ), thus allowing operating on
660 files whose sizes are greater than max_int .
661 Mapping files into memory
666 val map_file : file_descr -> ?pos:int64 -> kind:('a, 'b) Bigarray.kind
667 -> layout:'c Bigarray.layout -> shared:bool -> dims:int array -> ('a,
668 'b, 'c) Bigarray.Genarray.t
669 Memory mapping of a file as a Bigarray. map_file fd kind layout shared
671 dims returns a Bigarray of kind kind , layout layout , and dimensions
672 as specified in dims . The data contained in this Bigarray are the
673 contents of the file referred to by the file descriptor fd (as opened
674 previously with Unix.openfile , for example). The optional pos parame‐
675 ter is the byte offset in the file of the data being mapped; it
676 defaults to 0 (map from the beginning of the file).
677 If shared is true , all modifications performed on the array are
679 reflected in the file. This requires that fd be opened with write per‐
680 missions. If shared is false , modifications performed on the array
681 are done in memory only, using copy-on-write of the modified pages; the
682 underlying file is not affected.
683 Genarray.map_file is much more efficient than reading the whole file in
686 a Bigarray, modifying that Bigarray, and writing it afterwards.
687 To adjust automatically the dimensions of the Bigarray to the actual
689 size of the file, the major dimension (that is, the first dimension for
690 an array with C layout, and the last dimension for an array with For‐
691 tran layout) can be given as -1 . Genarray.map_file then determines
692 the major dimension from the size of the file. The file must contain
693 an integral number of sub-arrays as determined by the non-major dimen‐
694 sions, otherwise Failure is raised.
695 If all dimensions of the Bigarray are given, the file size is matched
697 against the size of the Bigarray. If the file is larger than the
698 Bigarray, only the initial portion of the file is mapped to the Bigar‐
699 ray. If the file is smaller than the big array, the file is automati‐
700 cally grown to the size of the Bigarray. This requires write permis‐
701 sions on fd .
702 Array accesses are bounds-checked, but the bounds are determined by the
704 initial call to map_file . Therefore, you should make sure no other
705 process modifies the mapped file while you're accessing it, or a SIGBUS
706 signal may be raised. This happens, for instance, if the file is
707 shrunk.
708 Invalid_argument or Failure may be raised in cases where argument vali‐
711 dation fails.
712 Since 4.06.0
715 Operations on file names
720 val unlink : string -> unit
721 Removes the named file
723 val rename : src:string -> dst:string -> unit
727 rename old new changes the name of a file from old to new .
730 val link : ?follow:bool -> src:string -> dst:string -> unit
734 link ?follow source dest creates a hard link named dest to the file
737 named source .
738 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
741 able.
742 Raises ENOSYS On Windows if ~follow:false is requested.
745 File permissions and ownership
750 type access_permission = Unix.access_permission =
751 | R_OK (* Read permission
752 *)
753 | W_OK (* Write permission
754 *)
755 | X_OK (* Execution permission
756 *)
757 | F_OK (* File exists
758 *)
759 Flags for the UnixLabels.access call.
762 val chmod : string -> perm:file_perm -> unit
766 Change the permissions of the named file.
768 val fchmod : file_descr -> perm:file_perm -> unit
772 Change the permissions of an opened file.
774 val chown : string -> uid:int -> gid:int -> unit
778 Change the owner uid and owner gid of the named file.
780 val fchown : file_descr -> uid:int -> gid:int -> unit
784 Change the owner uid and owner gid of an opened file.
786 val umask : int -> int
790 Set the process's file mode creation mask, and return the previous
792 mask.
793 val access : string -> perm:access_permission list -> unit
797 Check that the process has the given permissions over the named file.
799 Raise Unix_error otherwise.
800 Operations on file descriptors
805 val dup : ?cloexec:bool -> file_descr -> file_descr
806 Return a new file descriptor referencing the same file as the given
808 descriptor.
809 val dup2 : ?cloexec:bool -> src:file_descr -> dst:file_descr -> unit
813 dup2 fd1 fd2 duplicates fd1 to fd2 , closing fd2 if already opened.
816 val set_nonblock : file_descr -> unit
820 Set the ``non-blocking'' flag on the given descriptor. When the
822 non-blocking flag is set, reading on a descriptor on which there is
823 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
824 instead of blocking; writing on a descriptor on which there is tempo‐
825 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
826 val clear_nonblock : file_descr -> unit
830 Clear the ``non-blocking'' flag on the given descriptor. See UnixLa‐
832 bels.set_nonblock .
833 val set_close_on_exec : file_descr -> unit
837 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
839 with the close-on-exec flag is automatically closed when the current
840 process starts another program with one of the exec functions.
841 val clear_close_on_exec : file_descr -> unit
845 Clear the ``close-on-exec'' flag on the given descriptor. See UnixLa‐
847 bels.set_close_on_exec .
848 Directories
853 val mkdir : string -> perm:file_perm -> unit
854 Create a directory with the given permissions.
856 val rmdir : string -> unit
860 Remove an empty directory.
862 val chdir : string -> unit
866 Change the process working directory.
868 val getcwd : unit -> string
872 Return the name of the current working directory.
874 val chroot : string -> unit
878 Change the process root directory.
880 type dir_handle = Unix.dir_handle
883 The type of descriptors over opened directories.
886 val opendir : string -> dir_handle
890 Open a descriptor on a directory
892 val readdir : dir_handle -> string
896 Return the next entry in a directory.
898 Raises End_of_file when the end of the directory has been reached.
901 val rewinddir : dir_handle -> unit
905 Reposition the descriptor to the beginning of the directory
907 val closedir : dir_handle -> unit
911 Close a directory descriptor.
913 Pipes and redirections
918 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
919 Create a pipe. The first component of the result is opened for reading,
921 that's the exit to the pipe. The second component is opened for writ‐
922 ing, that's the entrance to the pipe.
923 val mkfifo : string -> perm:file_perm -> unit
927 Create a named pipe with the given permissions.
929 High-level process and redirection management
934 val create_process : prog:string -> args:string array ->
935 stdin:file_descr -> stdout:file_descr -> stderr:file_descr -> int
936 create_process prog args new_stdin new_stdout new_stderr forks a new
939 process that executes the program in file prog , with arguments args .
940 The pid of the new process is returned immediately; the new process
941 executes concurrently with the current process. The standard input and
942 outputs of the new process are connected to the descriptors new_stdin ,
943 new_stdout and new_stderr . Passing e.g. stdout for new_stdout pre‐
944 vents the redirection and causes the new process to have the same stan‐
945 dard output as the current process. The executable file prog is
946 searched in the path. The new process has the same environment as the
947 current process.
948 val create_process_env : prog:string -> args:string array -> env:string
952 array -> stdin:file_descr -> stdout:file_descr -> stderr:file_descr ->
953 int
954 create_process_env prog args env new_stdin new_stdout new_stderr works
957 as UnixLabels.create_process , except that the extra argument env spec‐
958 ifies the environment passed to the program.
959 val open_process_in : string -> in_channel
963 High-level pipe and process management. This function runs the given
965 command in parallel with the program. The standard output of the com‐
966 mand is redirected to a pipe, which can be read via the returned input
967 channel. The command is interpreted by the shell /bin/sh (cf. system
968 ).
969 val open_process_out : string -> out_channel
973 Same as UnixLabels.open_process_in , but redirect the standard input of
975 the command to a pipe. Data written to the returned output channel is
976 sent to the standard input of the command. Warning: writes on output
977 channels are buffered, hence be careful to call flush at the right
978 times to ensure correct synchronization.
979 val open_process : string -> in_channel * out_channel
983 Same as UnixLabels.open_process_out , but redirects both the standard
985 input and standard output of the command to pipes connected to the two
986 returned channels. The input channel is connected to the output of the
987 command, and the output channel to the input of the command.
988 val open_process_full : string -> env:string array -> in_channel *
992 out_channel * in_channel
993 Similar to UnixLabels.open_process , but the second argument specifies
995 the environment passed to the command. The result is a triple of chan‐
996 nels connected respectively to the standard output, standard input, and
997 standard error of the command.
998 val open_process_args_in : string -> string array -> in_channel
1002 High-level pipe and process management. The first argument specifies
1004 the command to run, and the second argument specifies the argument
1005 array passed to the command. This function runs the command in paral‐
1006 lel with the program. The standard output of the command is redirected
1007 to a pipe, which can be read via the returned input channel.
1008 Since 4.08.0
1011 val open_process_args_out : string -> string array -> out_channel
1015 Same as Unix.open_process_args_in , but redirect the standard input of
1017 the command to a pipe. Data written to the returned output channel is
1018 sent to the standard input of the command. Warning: writes on output
1019 channels are buffered, hence be careful to call flush at the right
1020 times to ensure correct synchronization.
1021 Since 4.08.0
1024 val open_process_args : string -> string array -> in_channel *
1028 out_channel
1029 Same as Unix.open_process_args_out , but redirects both the standard
1031 input and standard output of the command to pipes connected to the two
1032 returned channels. The input channel is connected to the output of the
1033 command, and the output channel to the input of the command.
1034 Since 4.08.0
1037 val open_process_args_full : string -> string array -> string array ->
1041 in_channel * out_channel * in_channel
1042 Similar to Unix.open_process_args , but the third argument specifies
1044 the environment passed to the command. The result is a triple of chan‐
1045 nels connected respectively to the standard output, standard input, and
1046 standard error of the command.
1047 Since 4.08.0
1050 val close_process_in : in_channel -> process_status
1054 Close channels opened by UnixLabels.open_process_in , wait for the
1056 associated command to terminate, and return its termination status.
1057 val close_process_out : out_channel -> process_status
1061 Close channels opened by UnixLabels.open_process_out , wait for the
1063 associated command to terminate, and return its termination status.
1064 val close_process : in_channel * out_channel -> process_status
1068 Close channels opened by UnixLabels.open_process , wait for the associ‐
1070 ated command to terminate, and return its termination status.
1071 val close_process_full : in_channel * out_channel * in_channel ->
1075 process_status
1076 Close channels opened by UnixLabels.open_process_full , wait for the
1078 associated command to terminate, and return its termination status.
1079 Symbolic links
1084 val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
1085 symlink source dest creates the file dest as a symbolic link to the
1088 file source . See Unix.symlink for details of ~to_dir
1089 val has_symlink : unit -> bool
1094 Returns true if the user is able to create symbolic links. On Windows,
1096 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1097 ilege but is also running elevated, if necessary. On other platforms,
1098 this is simply indicates that the symlink system call is available.
1099 Since 4.03.0
1102 val readlink : string -> string
1106 Read the contents of a link.
1108 Polling
1113 val select : read:file_descr list -> write:file_descr list ->
1114 except:file_descr list -> timeout:float -> file_descr list * file_descr
1115 list * file_descr list
1116 Wait until some input/output operations become possible on some chan‐
1118 nels. The three list arguments are, respectively, a set of descriptors
1119 to check for reading (first argument), for writing (second argument),
1120 or for exceptional conditions (third argument). The fourth argument is
1121 the maximal timeout, in seconds; a negative fourth argument means no
1122 timeout (unbounded wait). The result is composed of three sets of
1123 descriptors: those ready for reading (first component), ready for writ‐
1124 ing (second component), and over which an exceptional condition is
1125 pending (third component).
1126 Locking
1131 type lock_command = Unix.lock_command =
1132 | F_ULOCK (* Unlock a region
1133 *)
1134 | F_LOCK (* Lock a region for writing, and block if already locked
1135 *)
1136 | F_TLOCK (* Lock a region for writing, or fail if already locked
1137 *)
1138 | F_TEST (* Test a region for other process locks
1139 *)
1140 | F_RLOCK (* Lock a region for reading, and block if already locked
1141 *)
1142 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1143 *)
1144 Commands for UnixLabels.lockf .
1147 val lockf : file_descr -> mode:lock_command -> len:int -> unit
1151 lockf fd cmd size puts a lock on a region of the file opened as fd .
1154 The region starts at the current read/write position for fd (as set by
1155 UnixLabels.lseek ), and extends size bytes forward if size is positive,
1156 size bytes backwards if size is negative, or to the end of the file if
1157 size is zero. A write lock prevents any other process from acquiring a
1158 read or write lock on the region. A read lock prevents any other
1159 process from acquiring a write lock on the region, but lets other pro‐
1160 cesses acquire read locks on it.
1161 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1163 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1164 read lock on the specified region. If one or several locks put by
1165 another process prevent the current process from acquiring the lock,
1166 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1167 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1168 whatever locks the current process has on the specified region.
1169 Finally, the F_TEST command tests whether a write lock can be acquired
1170 on the specified region, without actually putting a lock. It returns
1171 immediately if successful, or fails otherwise.
1172 Signals
1177 Note: installation of signal handlers is performed via the functions
1178 Sys.signal and Sys.set_signal .
1179 val kill : pid:int -> signal:int -> unit
1181 kill pid sig sends signal number sig to the process with id pid .
1184 type sigprocmask_command = Unix.sigprocmask_command =
1187 | SIG_SETMASK
1188 | SIG_BLOCK
1189 | SIG_UNBLOCK
1190 val sigprocmask : mode:sigprocmask_command -> int list -> int list
1196 sigprocmask cmd sigs changes the set of blocked signals. If cmd is
1199 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1200 cmd is SIG_BLOCK , the signals in sigs are added to the set of blocked
1201 signals. If cmd is SIG_UNBLOCK , the signals in sigs are removed from
1202 the set of blocked signals. sigprocmask returns the set of previously
1203 blocked signals.
1204 val sigpending : unit -> int list
1208 Return the set of blocked signals that are currently pending.
1210 val sigsuspend : int list -> unit
1214 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1217 for a non-ignored, non-blocked signal to be delivered. On return, the
1218 blocked signals are reset to their initial value.
1219 val pause : unit -> unit
1223 Wait until a non-ignored, non-blocked signal is delivered.
1225 Time functions
1230 type process_times = Unix.process_times = {
1231 tms_utime : float ; (* User time for the process
1232 *)
1233 tms_stime : float ; (* System time for the process
1234 *)
1235 tms_cutime : float ; (* User time for the children processes
1236 *)
1237 tms_cstime : float ; (* System time for the children processes
1238 *)
1239 }
1240 The execution times (CPU times) of a process.
1243 type tm = Unix.tm = {
1246 tm_sec : int ; (* Seconds 0..60
1247 *)
1248 tm_min : int ; (* Minutes 0..59
1249 *)
1250 tm_hour : int ; (* Hours 0..23
1251 *)
1252 tm_mday : int ; (* Day of month 1..31
1253 *)
1254 tm_mon : int ; (* Month of year 0..11
1255 *)
1256 tm_year : int ; (* Year - 1900
1257 *)
1258 tm_wday : int ; (* Day of week (Sunday is 0)
1259 *)
1260 tm_yday : int ; (* Day of year 0..365
1261 *)
1262 tm_isdst : bool ; (* Daylight time savings in effect
1263 *)
1264 }
1265 The type representing wallclock time and calendar date.
1268 val time : unit -> float
1272 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1274 val gettimeofday : unit -> float
1278 Same as UnixLabels.time , but with resolution better than 1 second.
1280 val gmtime : float -> tm
1284 Convert a time in seconds, as returned by UnixLabels.time , into a date
1286 and a time. Assumes UTC (Coordinated Universal Time), also known as
1287 GMT.
1288 val localtime : float -> tm
1292 Convert a time in seconds, as returned by UnixLabels.time , into a date
1294 and a time. Assumes the local time zone.
1295 val mktime : tm -> float * tm
1299 Convert a date and time, specified by the tm argument, into a time in
1301 seconds, as returned by UnixLabels.time . The tm_isdst , tm_wday and
1302 tm_yday fields of tm are ignored. Also return a normalized copy of the
1303 given tm record, with the tm_wday , tm_yday , and tm_isdst fields
1304 recomputed from the other fields, and the other fields normalized (so
1305 that, e.g., 40 October is changed into 9 November). The tm argument is
1306 interpreted in the local time zone.
1307 val alarm : int -> int
1311 Schedule a SIGALRM signal after the given number of seconds.
1313 val sleep : int -> unit
1317 Stop execution for the given number of seconds.
1319 val times : unit -> process_times
1323 Return the execution times of the process.
1325 val utimes : string -> access:float -> modif:float -> unit
1329 Set the last access time (second arg) and last modification time (third
1331 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1332 1, 1970. A time of 0.0 is interpreted as the current time.
1333 type interval_timer = Unix.interval_timer =
1336 | ITIMER_REAL (* decrements in real time, and sends the signal
1337 SIGALRM when expired.
1338 *)
1339 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1340 SIGVTALRM when expired.
1341 *)
1342 | ITIMER_PROF (* (for profiling) decrements both when the process is
1343 running and when the system is running on behalf of the process; it
1344 sends SIGPROF when expired.
1345 *)
1346 The three kinds of interval timers.
1349 type interval_timer_status = Unix.interval_timer_status = {
1352 it_interval : float ; (* Period
1353 *)
1354 it_value : float ; (* Current value of the timer
1355 *)
1356 }
1357 The type describing the status of an interval timer
1360 val getitimer : interval_timer -> interval_timer_status
1364 Return the current status of the given interval timer.
1366 val setitimer : interval_timer -> interval_timer_status -> inter‐
1370 val_timer_status
1371 setitimer t s sets the interval timer t and returns its previous sta‐
1374 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1375 is the time to the next timer expiration; s.it_interval , if nonzero,
1376 specifies a value to be used in reloading it_value when the timer
1377 expires. Setting s.it_value to zero disable the timer. Setting
1378 s.it_interval to zero causes the timer to be disabled after its next
1379 expiration.
1380 User id, group id
1385 val getuid : unit -> int
1386 Return the user id of the user executing the process.
1388 val geteuid : unit -> int
1392 Return the effective user id under which the process runs.
1394 val setuid : int -> unit
1398 Set the real user id and effective user id for the process.
1400 val getgid : unit -> int
1404 Return the group id of the user executing the process.
1406 val getegid : unit -> int
1410 Return the effective group id under which the process runs.
1412 val setgid : int -> unit
1416 Set the real group id and effective group id for the process.
1418 val getgroups : unit -> int array
1422 Return the list of groups to which the user executing the process
1424 belongs.
1425 val setgroups : int array -> unit
1429 setgroups groups sets the supplementary group IDs for the calling
1432 process. Appropriate privileges are required.
1433 val initgroups : string -> int -> unit
1437 initgroups user group initializes the group access list by reading the
1440 group database /etc/group and using all groups of which user is a mem‐
1441 ber. The additional group group is also added to the list.
1442 type passwd_entry = Unix.passwd_entry = {
1445 pw_name : string ;
1446 pw_passwd : string ;
1447 pw_uid : int ;
1448 pw_gid : int ;
1449 pw_gecos : string ;
1450 pw_dir : string ;
1451 pw_shell : string ;
1452 }
1453 Structure of entries in the passwd database.
1456 type group_entry = Unix.group_entry = {
1459 gr_name : string ;
1460 gr_passwd : string ;
1461 gr_gid : int ;
1462 gr_mem : string array ;
1463 }
1464 Structure of entries in the groups database.
1467 val getlogin : unit -> string
1471 Return the login name of the user executing the process.
1473 val getpwnam : string -> passwd_entry
1477 Find an entry in passwd with the given name, or raise Not_found if the
1479 matching entry is not found.
1480 val getgrnam : string -> group_entry
1484 Find an entry in group with the given name, or raise Not_found if the
1486 matching entry is not found.
1487 val getpwuid : int -> passwd_entry
1491 Find an entry in passwd with the given user id, or raise Not_found if
1493 the matching entry is not found.
1494 val getgrgid : int -> group_entry
1498 Find an entry in group with the given group id, or raise Not_found if
1500 the matching entry is not found.
1501 Internet addresses
1506 type inet_addr = Unix.inet_addr
1507 The abstract type of Internet addresses.
1510 val inet_addr_of_string : string -> inet_addr
1514 Conversion from the printable representation of an Internet address to
1516 its internal representation. The argument string consists of 4 numbers
1517 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1518 8 numbers separated by colons for IPv6 addresses. Raise Failure when
1519 given a string that does not match these formats.
1520 val string_of_inet_addr : inet_addr -> string
1524 Return the printable representation of the given Internet address. See
1526 Unix.inet_addr_of_string for a description of the printable representa‐
1527 tion.
1528 val inet_addr_any : inet_addr
1532 A special IPv4 address, for use only with bind , representing all the
1534 Internet addresses that the host machine possesses.
1535 val inet_addr_loopback : inet_addr
1539 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1541 val inet6_addr_any : inet_addr
1545 A special IPv6 address, for use only with bind , representing all the
1547 Internet addresses that the host machine possesses.
1548 val inet6_addr_loopback : inet_addr
1552 A special IPv6 address representing the host machine ( ::1 ).
1554 Sockets
1559 type socket_domain = Unix.socket_domain =
1560 | PF_UNIX (* Unix domain
1561 *)
1562 | PF_INET (* Internet domain (IPv4)
1563 *)
1564 | PF_INET6 (* Internet domain (IPv6)
1565 *)
1566 The type of socket domains. Not all platforms support IPv6 sockets
1569 (type PF_INET6 ).
1570 type socket_type = Unix.socket_type =
1573 | SOCK_STREAM (* Stream socket
1574 *)
1575 | SOCK_DGRAM (* Datagram socket
1576 *)
1577 | SOCK_RAW (* Raw socket
1578 *)
1579 | SOCK_SEQPACKET (* Sequenced packets socket
1580 *)
1581 The type of socket kinds, specifying the semantics of communications.
1584 type sockaddr = Unix.sockaddr =
1587 | ADDR_UNIX of string
1588 | ADDR_INET of inet_addr * int
1589 (* The type of socket addresses. ADDR_UNIX name is a socket address
1590 in the Unix domain; name is a file name in the file system.
1591 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1592 is the Internet address of the machine, and port is the port number.
1593 *)
1594 val socket : ?cloexec:bool -> domain:socket_domain -> kind:socket_type
1600 -> protocol:int -> file_descr
1601 Create a new socket in the given domain, and with the given kind. The
1603 third argument is the protocol type; 0 selects the default protocol for
1604 that kind of sockets.
1605 val domain_of_sockaddr : sockaddr -> socket_domain
1609 Return the socket domain adequate for the given socket address.
1611 val socketpair : ?cloexec:bool -> domain:socket_domain ->
1615 kind:socket_type -> protocol:int -> file_descr * file_descr
1616 Create a pair of unnamed sockets, connected together.
1618 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1622 Accept connections on the given socket. The returned descriptor is a
1624 socket connected to the client; the returned address is the address of
1625 the connecting client.
1626 val bind : file_descr -> addr:sockaddr -> unit
1630 Bind a socket to an address.
1632 val connect : file_descr -> addr:sockaddr -> unit
1636 Connect a socket to an address.
1638 val listen : file_descr -> max:int -> unit
1642 Set up a socket for receiving connection requests. The integer argument
1644 is the maximal number of pending requests.
1645 type shutdown_command = Unix.shutdown_command =
1648 | SHUTDOWN_RECEIVE (* Close for receiving
1649 *)
1650 | SHUTDOWN_SEND (* Close for sending
1651 *)
1652 | SHUTDOWN_ALL (* Close both
1653 *)
1654 The type of commands for shutdown .
1657 val shutdown : file_descr -> mode:shutdown_command -> unit
1661 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
1663 reads on the other end of the connection to return an end-of-file con‐
1664 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
1665 tion to return a closed pipe condition ( SIGPIPE signal).
1666 val getsockname : file_descr -> sockaddr
1670 Return the address of the given socket.
1672 val getpeername : file_descr -> sockaddr
1676 Return the address of the host connected to the given socket.
1678 type msg_flag = Unix.msg_flag =
1681 | MSG_OOB
1682 | MSG_DONTROUTE
1683 | MSG_PEEK (* The flags for UnixLabels.recv , UnixLabels.recvfrom ,
1684 UnixLabels.send and UnixLabels.sendto .
1685 *)
1686 val recv : file_descr -> buf:bytes -> pos:int -> len:int ->
1692 mode:msg_flag list -> int
1693 Receive data from a connected socket.
1695 val recvfrom : file_descr -> buf:bytes -> pos:int -> len:int ->
1699 mode:msg_flag list -> int * sockaddr
1700 Receive data from an unconnected socket.
1702 val send : file_descr -> buf:bytes -> pos:int -> len:int ->
1706 mode:msg_flag list -> int
1707 Send data over a connected socket.
1709 val send_substring : file_descr -> buf:string -> pos:int -> len:int ->
1713 mode:msg_flag list -> int
1714 Same as send , but take the data from a string instead of a byte
1716 sequence.
1717 Since 4.02.0
1720 val sendto : file_descr -> buf:bytes -> pos:int -> len:int ->
1724 mode:msg_flag list -> addr:sockaddr -> int
1725 Send data over an unconnected socket.
1727 val sendto_substring : file_descr -> buf:string -> pos:int -> len:int
1731 -> mode:msg_flag list -> sockaddr -> int
1732 Same as sendto , but take the data from a string instead of a byte
1734 sequence.
1735 Since 4.02.0
1738 Socket options
1743 type socket_bool_option =
1744 | SO_DEBUG (* Record debugging information
1745 *)
1746 | SO_BROADCAST (* Permit sending of broadcast messages
1747 *)
1748 | SO_REUSEADDR (* Allow reuse of local addresses for bind
1749 *)
1750 | SO_KEEPALIVE (* Keep connection active
1751 *)
1752 | SO_DONTROUTE (* Bypass the standard routing algorithms
1753 *)
1754 | SO_OOBINLINE (* Leave out-of-band data in line
1755 *)
1756 | SO_ACCEPTCONN (* Report whether socket listening is enabled
1757 *)
1758 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
1759 *)
1760 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
1761 *)
1762 The socket options that can be consulted with UnixLabels.getsockopt and
1765 modified with UnixLabels.setsockopt . These options have a boolean (
1766 true / false ) value.
1767 type socket_int_option =
1770 | SO_SNDBUF (* Size of send buffer
1771 *)
1772 | SO_RCVBUF (* Size of received buffer
1773 *)
1774 | SO_ERROR (* Deprecated. Use Unix.getsockopt_error instead.
1775 *)
1776 | SO_TYPE (* Report the socket type
1777 *)
1778 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
1779 tions
1780 *)
1781 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
1782 tions
1783 *)
1784 The socket options that can be consulted with UnixLabels.getsockopt_int
1787 and modified with UnixLabels.setsockopt_int . These options have an
1788 integer value.
1789 type socket_optint_option =
1792 | SO_LINGER (* Whether to linger on closed connections that have data
1793 present, and for how long (in seconds)
1794 *)
1795 The socket options that can be consulted with Unix.getsockopt_optint
1798 and modified with Unix.setsockopt_optint . These options have a value
1799 of type int option , with None meaning ``disabled''.
1800 type socket_float_option =
1803 | SO_RCVTIMEO (* Timeout for input operations
1804 *)
1805 | SO_SNDTIMEO (* Timeout for output operations
1806 *)
1807 The socket options that can be consulted with UnixLabels.getsock‐
1810 opt_float and modified with UnixLabels.setsockopt_float . These
1811 options have a floating-point value representing a time in seconds.
1812 The value 0 means infinite timeout.
1813 val getsockopt : file_descr -> socket_bool_option -> bool
1817 Return the current status of a boolean-valued option in the given
1819 socket.
1820 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
1824 Set or clear a boolean-valued option in the given socket.
1826 val getsockopt_int : file_descr -> socket_int_option -> int
1830 Same as Unix.getsockopt for an integer-valued socket option.
1832 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
1836 Same as Unix.setsockopt for an integer-valued socket option.
1838 val getsockopt_optint : file_descr -> socket_optint_option -> int
1842 option
1843 Same as Unix.getsockopt for a socket option whose value is an int
1845 option .
1846 val setsockopt_optint : file_descr -> socket_optint_option -> int
1850 option -> unit
1851 Same as Unix.setsockopt for a socket option whose value is an int
1853 option .
1854 val getsockopt_float : file_descr -> socket_float_option -> float
1858 Same as Unix.getsockopt for a socket option whose value is a float‐
1860 ing-point number.
1861 val setsockopt_float : file_descr -> socket_float_option -> float ->
1865 unit
1866 Same as Unix.setsockopt for a socket option whose value is a float‐
1868 ing-point number.
1869 val getsockopt_error : file_descr -> error option
1873 Return the error condition associated with the given socket, and clear
1875 it.
1876 High-level network connection functions
1881 val open_connection : sockaddr -> in_channel * out_channel
1882 Connect to a server at the given address. Return a pair of buffered
1884 channels connected to the server. Remember to call flush on the output
1885 channel at the right times to ensure correct synchronization.
1886 val shutdown_connection : in_channel -> unit
1890 ``Shut down'' a connection established with UnixLabels.open_connection
1892 ; that is, transmit an end-of-file condition to the server reading on
1893 the other side of the connection.
1894 val establish_server : (in_channel -> out_channel -> unit) ->
1898 addr:sockaddr -> unit
1899 Establish a server on the given address. The function given as first
1901 argument is called for each connection with two buffered channels con‐
1902 nected to the client. A new process is created for each connection. The
1903 function UnixLabels.establish_server never returns normally.
1904 Host and protocol databases
1909 type host_entry = Unix.host_entry = {
1910 h_name : string ;
1911 h_aliases : string array ;
1912 h_addrtype : socket_domain ;
1913 h_addr_list : inet_addr array ;
1914 }
1915 Structure of entries in the hosts database.
1918 type protocol_entry = Unix.protocol_entry = {
1921 p_name : string ;
1922 p_aliases : string array ;
1923 p_proto : int ;
1924 }
1925 Structure of entries in the protocols database.
1928 type service_entry = Unix.service_entry = {
1931 s_name : string ;
1932 s_aliases : string array ;
1933 s_port : int ;
1934 s_proto : string ;
1935 }
1936 Structure of entries in the services database.
1939 val gethostname : unit -> string
1943 Return the name of the local host.
1945 val gethostbyname : string -> host_entry
1949 Find an entry in hosts with the given name, or raise Not_found .
1951 val gethostbyaddr : inet_addr -> host_entry
1955 Find an entry in hosts with the given address, or raise Not_found .
1957 val getprotobyname : string -> protocol_entry
1961 Find an entry in protocols with the given name, or raise Not_found .
1963 val getprotobynumber : int -> protocol_entry
1967 Find an entry in protocols with the given protocol number, or raise
1969 Not_found .
1970 val getservbyname : string -> protocol:string -> service_entry
1974 Find an entry in services with the given name, or raise Not_found .
1976 val getservbyport : int -> protocol:string -> service_entry
1980 Find an entry in services with the given service number, or raise
1982 Not_found .
1983 type addr_info = {
1986 ai_family : socket_domain ; (* Socket domain
1987 *)
1988 ai_socktype : socket_type ; (* Socket type
1989 *)
1990 ai_protocol : int ; (* Socket protocol number
1991 *)
1992 ai_addr : sockaddr ; (* Address
1993 *)
1994 ai_canonname : string ; (* Canonical host name
1995 *)
1996 }
1997 Address information returned by Unix.getaddrinfo .
2000 type getaddrinfo_option =
2003 | AI_FAMILY of socket_domain
2004 (* Impose the given socket domain
2005 *)
2006 | AI_SOCKTYPE of socket_type
2007 (* Impose the given socket type
2008 *)
2009 | AI_PROTOCOL of int
2010 (* Impose the given protocol
2011 *)
2012 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP
2013 address
2014 *)
2015 | AI_CANONNAME (* Fill the ai_canonname field of the result
2016 *)
2017 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
2018 *)
2020 Options to Unix.getaddrinfo .
2023 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2027 addr_info list
2028 getaddrinfo host service opts returns a list of Unix.addr_info records
2031 describing socket parameters and addresses suitable for communicating
2032 with the given host and service. The empty list is returned if the
2033 host or service names are unknown, or the constraints expressed in opts
2034 cannot be satisfied.
2035 host is either a host name or the string representation of an IP
2038 address. host can be given as the empty string; in this case, the
2039 ``any'' address or the ``loopback'' address are used, depending whether
2040 opts contains AI_PASSIVE . service is either a service name or the
2041 string representation of a port number. service can be given as the
2042 empty string; in this case, the port field of the returned addresses is
2043 set to 0. opts is a possibly empty list of options that allows the
2044 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2045 only) or a particular socket type (e.g. TCP only or UDP only).
2046 type name_info = {
2049 ni_hostname : string ; (* Name or IP address of host
2050 *)
2051 ni_service : string ; (* Name of service or port number
2052 *)
2053 }
2054 Host and service information returned by Unix.getnameinfo .
2057 type getnameinfo_option =
2060 | NI_NOFQDN (* Do not qualify local host names
2061 *)
2062 | NI_NUMERICHOST (* Always return host as IP address
2063 *)
2064 | NI_NAMEREQD (* Fail if host name cannot be determined
2065 *)
2066 | NI_NUMERICSERV (* Always return service as port number
2067 *)
2068 | NI_DGRAM (* Consider the service as UDP-based instead of the
2069 default TCP
2070 *)
2071 Options to Unix.getnameinfo .
2074 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2078 getnameinfo addr opts returns the host name and service name corre‐
2081 sponding to the socket address addr . opts is a possibly empty list of
2082 options that governs how these names are obtained. Raise Not_found if
2083 an error occurs.
2084 Terminal interface
2089 The following functions implement the POSIX standard terminal inter‐
2090 face. They provide control over asynchronous communication ports and
2091 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2092 tion.
2093 type terminal_io = Unix.terminal_io = {
2095 mutable c_ignbrk : bool ; (* Ignore the break condition.
2097 *)
2098 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2100 *)
2101 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2103 *)
2104 mutable c_parmrk : bool ; (* Mark parity errors.
2106 *)
2107 mutable c_inpck : bool ; (* Enable parity check on input.
2109 *)
2110 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2112 *)
2113 mutable c_inlcr : bool ; (* Map NL to CR on input.
2115 *)
2116 mutable c_igncr : bool ; (* Ignore CR on input.
2118 *)
2119 mutable c_icrnl : bool ; (* Map CR to NL on input.
2121 *)
2122 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2124 *)
2125 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2127 *)
2128 mutable c_opost : bool ; (* Enable output processing.
2130 *)
2131 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2133 tion).
2134 *)
2135 mutable c_ibaud : int ; (* Input baud rate.
2137 *)
2138 mutable c_csize : int ; (* Number of bits per character (5-8).
2140 *)
2141 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2143 *)
2144 mutable c_cread : bool ; (* Reception is enabled.
2146 *)
2147 mutable c_parenb : bool ; (* Enable parity generation and detection.
2149 *)
2150 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2152 *)
2153 mutable c_hupcl : bool ; (* Hang up on last close.
2155 *)
2156 mutable c_clocal : bool ; (* Ignore modem status lines.
2158 *)
2159 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2161 *)
2162 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2164 ing and editing)
2165 *)
2166 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2168 *)
2169 mutable c_echo : bool ; (* Echo input characters.
2171 *)
2172 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2174 *)
2175 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2177 *)
2178 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2180 *)
2181 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2183 *)
2184 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2186 *)
2187 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2189 *)
2190 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2192 *)
2193 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2195 *)
2196 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2198 *)
2199 mutable c_vmin : int ; (* Minimum number of characters to read before
2201 the read request is satisfied.
2202 *)
2203 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2205 *)
2206 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2208 *)
2209 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2211 *)
2212 }
2213 val tcgetattr : file_descr -> terminal_io
2219 Return the status of the terminal referred to by the given file
2221 descriptor.
2222 type setattr_when = Unix.setattr_when =
2225 | TCSANOW
2226 | TCSADRAIN
2227 | TCSAFLUSH
2228 val tcsetattr : file_descr -> mode:setattr_when -> terminal_io -> unit
2234 Set the status of the terminal referred to by the given file descrip‐
2236 tor. The second argument indicates when the status change takes place:
2237 immediately ( TCSANOW ), when all pending output has been transmitted (
2238 TCSADRAIN ), or after flushing all input that has been received but not
2239 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2240 parameters; TCSAFLUSH , when changing the input parameters.
2241 val tcsendbreak : file_descr -> duration:int -> unit
2245 Send a break condition on the given file descriptor. The second argu‐
2247 ment is the duration of the break, in 0.1s units; 0 means standard
2248 duration (0.25s).
2249 val tcdrain : file_descr -> unit
2253 Waits until all output written on the given file descriptor has been
2255 transmitted.
2256 type flush_queue = Unix.flush_queue =
2259 | TCIFLUSH
2260 | TCOFLUSH
2261 | TCIOFLUSH
2262 val tcflush : file_descr -> mode:flush_queue -> unit
2268 Discard data written on the given file descriptor but not yet transmit‐
2270 ted, or data received but not yet read, depending on the second argu‐
2271 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2272 data written but not transmitted, and TCIOFLUSH flushes both.
2273 type flow_action = Unix.flow_action =
2276 | TCOOFF
2277 | TCOON
2278 | TCIOFF
2279 | TCION
2280 val tcflow : file_descr -> mode:flow_action -> unit
2286 Suspend or restart reception or transmission of data on the given file
2288 descriptor, depending on the second argument: TCOOFF suspends output,
2289 TCOON restarts output, TCIOFF transmits a STOP character to suspend
2290 input, and TCION transmits a START character to restart input.
2291 val setsid : unit -> int
2295 Put the calling process in a new session and detach it from its con‐
2297 trolling terminal.
2298OCamldoc 2019-07-30 UnixLabels(3)