23

I need to find help for point command . such as in . ./my_script.sh (I mean the first point.)

I have already tried to find a man page using man . and man \.. How can I display a man page in which it explains the use of command .?

Peter Mortensen
  • 12,190
aturegano
  • 461
  • @n8te I am referring to the first point in . ./my_script.sh. I know it is not the same to execute . ./my_script.sh than ./my_script.sh. . ./my_script.sh will behave similar than source ./my_script.sh – aturegano Mar 22 '18 at 08:26
  • Yes, my mistake. I didn't see the first dot. – n8te Mar 22 '18 at 08:27
  • 14
    @C0deDaedalus: The canonical name for "." is FULL STOP. What people call it depends on where they were raised. – RedGrittyBrick Mar 22 '18 at 11:24
  • 1
    Related: https://superuser.com/questions/728931/what-does-bashrc-actually-do – Dmitry Grigoryev Mar 22 '18 at 12:29
  • 5
    Just run: help . – kenorb Mar 22 '18 at 14:17
  • 2
    In the docs, though, it's called dot. See the formal specification at http://pubs.opengroup.org/onlinepubs/009696699/utilities/dot.html – Charles Duffy Mar 22 '18 at 17:13
  • Perhaps the first thing you need to realize is that "." and ".." are NOT commands. They are parts of paths. "." means the current directory, so if you type "./some_file" at a prompt, the system will try to execute that file in the current directory. But if you type say "vi ./some_file", it will run vi to edit the file. Likewise, ".." means the parent directory. – jamesqf Mar 22 '18 at 17:58
  • 11
    @jamesqf . is a command, specifically a shell builtin. In Bash it's equivalent to source. – wjandrea Mar 22 '18 at 19:51
  • @wjandrea: The OP is asking about nix, not bash, which is not the only shell in existence. "." may be a command in bash (there doesn't appear to be a man page for bash on my system), but I use a different shell in which it does not appear to be. If you expect bash-specific things to apply to nix in general, you will eventually be disappointed :-) – jamesqf Mar 22 '18 at 21:38
  • @jamesqf I mentioned Bash just to give some context, if you were more familiar with it. In the Bourne shell, . is a shell builtin. – wjandrea Mar 22 '18 at 21:48
  • 1
    @RedGrittyBrick: Though true in the context of Unicode canonical names, unfortunately, that was a misleading choice on the part of the consortium. In reality, "full stop" is the name of a punctuation mark in English, which is usually represented by the symbol ., whose name is "period" (and which has many other uses, including the use discussed in the question). This is similar to how an "exclamation mark" is "implemented" by the symbol !, which is called "pling". Other uses for pling include the factorial notation in mathematics. – Lightness Races in Orbit Mar 22 '18 at 23:05
  • Possible duplicate of How can I easily see the man page for builtin shell commands? – muru Mar 23 '18 at 00:54
  • 4
    @jamesqf: . is POSIX, not just bash. E.g. it's also in zsh and ksh. – MSalters Mar 23 '18 at 14:59
  • 2
    The official name of the command is dot. – chepner Mar 23 '18 at 17:54
  • 1
    @MSalters: Isn't in tcsh, though, which was my point. It applies to particular shells, not universally. – jamesqf Mar 23 '18 at 18:09
  • man command takes to the common man page for all builtin commands and help command shows the command specific information. – codeforester Mar 28 '18 at 21:33

5 Answers5

80

First of all you should invoke type ., you will probably get something like:

. is a shell builtin

Builtins are parts of your shell, they don't have their own manual pages. Some of them may seem to have them though, e.g. echo is a builtin in Bash but most likely there is a separate executable like /bin/echo in your system and in this case man echo refers to the latter. These two echos are probably not strictly equivalent.

Your shell may provide information about any builtin via help builtin; try help help, help type and finally:

help .

Builtins may also be listed in your shell's manual page. E.g. (in my Debian) Bash builtins are covered directly in man bash, yet for Zsh builtins man zsh tells me to run man zshbuiltins. In general shells may or may not explain their builtins.

Kamil Maciorowski
  • 74,068
  • 7
    +1 for pointing that . is a shell-built-in and This should be marked as answer because OP asks how to find help for . in *nix ?. – C0deDaedalus Mar 22 '18 at 11:45
  • 8
    +1 for the use of type . to demonstrate that some commands are shell builtins. – Roger Lipscombe Mar 22 '18 at 11:53
  • 2
    On most Debian, Bash builtins are also extracted to the bash-builtins(1) manual page, which is of a more convenient size. – Toby Speight Mar 22 '18 at 14:06
  • 1
    Also, invoking "type" only works if you're using a shell which has a "type" builtin. If you happen to be using tcsh, "type ." gives "type: Command not found." – jamesqf Mar 22 '18 at 21:43
  • +1 for the use of type . to tell you what to research next. Lego. – Lightness Races in Orbit Mar 22 '18 at 23:08
  • 1
    Even . --help works – Digital Trauma Mar 23 '18 at 18:17
  • So I tried "help ." and I get "help: no entry for . in the manual.". (Same for "help source", giving "help: no entry for source in the manual.") I suspect that if you're experiencing more elaborate output, that may be a bash-ism (and suspect that is why this entry ended up getting upvoted so much) – TOOGAM Mar 24 '18 at 17:58
24

Try using man sh or man bash or the man page for whatever shell you are using. (Maybe man $SHELL.)

This is officially not called the "point" command, but the source command. Searching for the word source may be helpful.

e.g., bash man page (search for "each builtin command"), and you'll quickly find the documentation.

As for explaining the use, I can do that right here. I will just refer to this as the source command, recognizing that it can be abbreviated to just a period when you're using some shells, and with some shells that command might need to be (because dot might be recognized but the entire word source might not be).

If you use the source command, your shell will read each line from the script file, and try to execute it. You need "read" permissions on the file. (It doesn't matter if you have "execute" permissions.) If you modify a variable, that is prone to affecting your current shell.

If, on the other hand, you just try to execute the file, then your shell will ask the operating system to take care of this request. This will require "execute" permissions. (On some systems, like OpenBSD, you won't need "read" permissions for this. On other systems, including many Unix variations, you will.) The file may need to start with an appropriate header (e.g., #!/bin/sh) so the operating system recognizes this to be a script file. The operating system will execute a copy of the requested shell, and tell that shell to run the contents of the script. If the shell environment is changed (e.g., a variable gets a new value, the working directory is changed (with cd), a file descriptor is redirected (with exec), etc.), it will impact only the sub-shell that was called for the script, and can't modify the environment in the parent shell that called the script file.

TOOGAM
  • 15,798
  • 5
  • 43
  • 63
  • 15
    It's only source in bash. In the POSIX specification, it's called "the dot command" (and the source alias is not supported). – Charles Duffy Mar 22 '18 at 17:13
  • 1
    A script needs read permissions, otherwise the interpreter can't access it. See Can a script be executable but not readable? – wjandrea Mar 22 '18 at 20:04
  • 1
    Executing a script doesn't open a sub-shell, but just a normal child process, just like running a compiled program. See this answer on "Is a sub-shell the same thing as a child-shell?" – wjandrea Mar 22 '18 at 20:21
  • 1
    So, I type man bash and then what, /.? Not very useful. /source would be useful, but for that you'd need to know that . and source are the same thing. – Joker_vD Mar 23 '18 at 12:40
  • @Joker_vD : On most systems I've come across, there is no man page for "." or "source", so the only official documentation related to this command is the text located in the man page for the shell. I simply answered the question of where a person can find that official documentation, since that is what aturegano asked. Right. If you use / to search, and search for period, you get lots of unrelated periods. Hey! Don't blame me if the man page's design isn't clear enough for you to like it. I didn't design this. I'm just helping to successfully deal with how things actually are. – TOOGAM Mar 24 '18 at 16:27
  • @wjandrea : Tests have found that exact effect depends on what system is being used. Question was tagged with both unix and linux, so my earlier statement was just as accurate and applicable as your early comment that indicated different behavior. There are different results in different environments. Sometimes, such read permission is required to "execute" a script, as you noted. In other environments, such permissions are not needed. (I've updated the text of the answer to better mention the different possibilities that may be experienced.) – TOOGAM Mar 24 '18 at 16:40
  • 1
    I found your paragraph "As for explaining the use..." slightly misleading, since it implies that it might be . and it might be source, but as @CharlesDuffy already mentioned, it's always . in any POSIX-compliant shell and only has the alias source in one shell. – Tom Fenech Mar 24 '18 at 17:40
  • @TomFenech : I wasn't misleading. I very much was saying specifically that. No implication was intended. Charles Duffy was wrong. – TOOGAM Mar 24 '18 at 17:47
  • @CharlesDuffy : bash offers both commands ; this does not mean that one command but not the other is universally accepted. In fact, I have found evidence proving that is not true, in both directions. In OpenBSD's ksh, dot works but the word "source" does not. In csh, it is called "souce", and not dot. If you try to run dot, it will try to "run" the filesystem object called dot (the current directory) and you'll get a permissions issue. (The question did not rule out csh, as it specified operating systems, but not what shell was being referred to.) – TOOGAM Mar 24 '18 at 17:51
  • Bringing up csh and tcsh is essentially obfuscation. I know of no distro where csh or tcsh is default; POSIX-y shells are both de facto and de jure standard, to the point that the StackOverflow shell tag explicitly indicates that POSIX is to be assumed in any discussion within that tag absent explicit contrary specification (granted, I haven't checked the tag wiki here on SU). – Charles Duffy Mar 24 '18 at 22:25
  • @CharlesDuffy : I don't use either, and didn't offhand recall which shells didn't support dot or source (I had to go checking), but I always remembered that neither command is universally supported. Alleging obfuscation seems like a rather attacking claim and I defend my intent of not trying to mislead. When I answered, I simply tried to support choice and compatibility. When I was first introduced to Unix, I was taught csh was viable and the most proper approach was to support it. (I've since read a bit more about csh's bugginess and general unsuitability.) I wasn't aware POSIX excluded csh – TOOGAM Mar 25 '18 at 00:41
6

No one else has mentioned it, as it's often forgotten.

Your biggest clue would of come from the helpful command whatis.

tim@musha ~ $ whatis .
builtins (1)         - bash built-in commands, see bash(1)
tim@musha ~ $ whatis source
builtins (1)         - bash built-in commands, see bash(1)
tim@musha ~ $ whatis bash
bash (1)             - GNU Bourne-Again SHell
tim@musha ~ $ whatis lynx
lynx (1)             - a general purpose distributed information browser for the World Wide Web
tim@musha ~ $ whatis linux
linux: nothing appropriate.
tim@musha ~ $ whatis whatis
whatis (1)           - display one-line manual page descriptions

EDIT:

Some people have pointed out in the comments that this isn't in some distrobutions - maybe it's an installable package, or enabled some how - I had it by default in gentoo ;)

It includes the wonderful which - which tells you which executable is called, and whereis which gives you all the paths to a executable you name, and it's man pages (if it exists in multiple paths).

djsmiley2kStaysInside
  • 6,713
  • 1
    Good hint but it seems it not works everywhere. For instance, in AIX with ksh, whatis . returns man: 0703-307 . is not found. – aturegano Mar 22 '18 at 16:43
  • 4
    whatis . returns nothing on Ubuntu 16.04 – Vadim Kotov Mar 22 '18 at 17:39
  • And ".: nothing appropriate." on OpenSuSE using tcsh. – jamesqf Mar 22 '18 at 21:45
  • 2
    Ah, from it's own man page: "whatis - display one-line manual page descriptions." So it appears to be a very very short version of man. – Xen2050 Mar 23 '18 at 10:34
  • A more compatible option may be: apropos (which should be the same as running "man -k"). For "." or "source" (which is part of the word "resource") this doesn't work too well, due to too many false positives, but likely would work for your other examples (bash, lynx, and whatis). On Debian Linux: "whatis ." gave ".: nothing appropriate." on OpenBSD, it resulted in 47 lines of output. For this specific example (using "whatis ." in Gentoo), the results may happen to just be uncommonly good (meaning that this technique isn't generally as useful for many other example scenarios). – TOOGAM Mar 25 '18 at 02:00
  • @TOOGAM .... it may work well for you, but tim@musha ~ $ apropos . | wc -l 13250 – djsmiley2kStaysInside Mar 25 '18 at 17:18
4

man source will show the explanation that you need.

The dot is the same as the source command.

source executes the script in the current shell instead of in a subshell (it's the usual way).

Using source the variables set inside the script are preserved after the script has finished.

jcbermu
  • 17,526
0

The . is a synonym for the shell source command and so in bash, its syntax is displayed by...

help source

It functions exactly like the include and import commands in other languages in that it reads the target file and interprets it as if it were part of the current script. Thus, that file will execute in its entirety before the commands in the rest of the current script.

It should usually be at the beginning of the current script and is most often used to load variables and/or function definitions.

DocSalvager
  • 320